# 🔧 **apt-ostree Troubleshooting Guide**

## 🚨 **Common Issues and Solutions**

This guide provides solutions for common problems encountered when using apt-ostree. For detailed architecture information, refer to the relevant documents in the `architecture/` directory.

## 🔍 **Diagnostic Commands**

### **System Status Check**
```bash
# Check system status
apt-ostree status

# Check daemon status
systemctl status aptostreed

# Check OSTree status
ostree admin status

# Check system logs
journalctl -u aptostreed -f
```

### **Package Information**
```bash
# List installed packages
apt-ostree db list

# Check package overrides
apt-ostree override list

# Check user overlays
apt-ostree usroverlay list

# Check live updates
apt-ostree apply-live status
```

## ❌ **Common Error Messages**

### **Permission Denied Errors**

#### **Error**: `Permission denied` or `Operation not permitted`
**Cause**: Command requires root privileges or Polkit authorization
**Solution**:
```bash
# Run with sudo
sudo apt-ostree <command>

# Check Polkit policies
pkaction --action org.projectatomic.aptostree.<action>

# Verify user permissions
groups $USER
```

#### **Error**: `Polkit authorization denied`
**Cause**: User lacks required Polkit permissions
**Solution**:
```bash
# Check Polkit configuration
ls /usr/share/polkit-1/actions/org.projectatomic.aptostree.policy

# Verify policy installation
sudo apt install apt-ostree-polkit

# Check user session
loginctl show-user $USER
```

### **Daemon Connection Errors**

#### **Error**: `Failed to connect to daemon` or `Daemon not running`
**Cause**: aptostreed daemon is not running or not accessible
**Solution**:
```bash
# Start the daemon
sudo apt-ostree start-daemon

# Check daemon status
systemctl status aptostreed

# Check DBus connection
busctl --user list | grep aptostree

# Restart daemon
sudo systemctl restart aptostreed
```

#### **Error**: `DBus connection failed`
**Cause**: DBus communication issues
**Solution**:
```bash
# Check DBus service
systemctl status dbus

# Restart DBus
sudo systemctl restart dbus

# Check DBus logs
journalctl -u dbus -f

# Verify user session
loginctl show-user $USER
```

### **OSTree Errors**

#### **Error**: `OSTree repository not found` or `Invalid OSTree path`
**Cause**: OSTree repository is corrupted or missing
**Solution**:
```bash
# Check OSTree repository
ostree admin status

# Verify repository integrity
ostree fsck

# Check repository path
ls -la /ostree/repo/

# Reinitialize repository (if necessary)
sudo ostree admin init-fs /
```

#### **Error**: `Deployment not found` or `Invalid deployment`
**Cause**: OSTree deployment is corrupted or missing
**Solution**:
```bash
# List deployments
ostree admin status

# Check deployment paths
ls -la /ostree/deploy/

# Verify boot configuration
ls -la /boot/loader/entries/

# Check systemd-boot configuration
bootctl status
```

### **Package Management Errors**

#### **Error**: `Package not found` or `Package installation failed`
**Cause**: Package not available or dependency issues
**Solution**:
```bash
# Update package lists
sudo apt update

# Check package availability
apt-cache search <package>

# Check package dependencies
apt-cache show <package>

# Verify APT configuration
cat /etc/apt/sources.list
```

#### **Error**: `Package conflict detected`
**Cause**: Package conflicts with existing system
**Solution**:
```bash
# Check package conflicts
apt-ostree db diff

# List package overrides
apt-ostree override list

# Check user overlays
apt-ostree usroverlay list

# Resolve conflicts manually
sudo apt-ostree override reset <package>
```

### **Filesystem Errors**

#### **Error**: `Overlay mount failed` or `Filesystem error`
**Cause**: OverlayFS or filesystem issues
**Solution**:
```bash
# Check overlay support
cat /proc/filesystems | grep overlay

# Check mount points
mount | grep overlay

# Verify filesystem space
df -h

# Check for corrupted overlays
sudo apt-ostree usroverlay list
sudo apt-ostree usroverlay remove <overlay>
```

## 🛠️ **Recovery Procedures**

### **System Recovery**

#### **Recover from Failed Update**
```bash
# Check current status
apt-ostree status

# Rollback to previous deployment
sudo apt-ostree rollback --reboot

# If rollback fails, boot from previous deployment
# Edit bootloader configuration manually
```

#### **Recover Corrupted Repository**
```bash
# Stop daemon
sudo systemctl stop aptostreed

# Check repository integrity
sudo ostree fsck

# Repair repository
sudo ostree fsck --repair

# Restart daemon
sudo systemctl start aptostreed
```

#### **Recover from Boot Failure**
```bash
# Boot into recovery mode or previous deployment
# Check boot configuration
ls -la /boot/loader/entries/

# Verify deployment integrity
ostree admin status

# Reinstall bootloader if necessary
sudo bootctl install
```

### **Package Recovery**

#### **Remove Problematic Packages**
```bash
# List installed packages
apt-ostree db list

# Remove problematic package
sudo apt-ostree uninstall <package>

# Check for remaining issues
apt-ostree status
```

#### **Reset Package Overrides**
```bash
# List overrides
apt-ostree override list

# Reset specific override
sudo apt-ostree override reset <package>

# Reset all overrides
sudo apt-ostree reset --packages
```

#### **Clean User Overlays**
```bash
# List overlays
apt-ostree usroverlay list

# Remove specific overlay
sudo apt-ostree usroverlay remove <overlay>

# Clean all overlays
sudo apt-ostree cleanup --overlays
```

## 📊 **Performance Issues**

### **Slow Operations**

#### **Slow Package Installation**
**Symptoms**: Package installation takes unusually long time
**Solutions**:
```bash
# Check system resources
htop
iostat -x 1

# Check disk I/O
iotop

# Verify network connectivity
ping -c 3 deb.debian.org

# Check APT cache
apt-cache policy <package>
```

#### **Slow System Updates**
**Symptoms**: System updates are slow or hang
**Solutions**:
```bash
# Check OSTree repository size
du -sh /ostree/repo/

# Clean old deployments
sudo apt-ostree cleanup

# Check for pending transactions
apt-ostree status

# Restart daemon
sudo systemctl restart aptostreed
```

### **Memory Issues**

#### **High Memory Usage**
**Symptoms**: System becomes unresponsive, high memory usage
**Solutions**:
```bash
# Check memory usage
free -h
ps aux --sort=-%mem | head

# Check for memory leaks
valgrind --tool=memcheck apt-ostree status

# Restart daemon
sudo systemctl restart aptostreed
```

## 🔒 **Security Issues**

### **Authorization Problems**

#### **Polkit Policy Issues**
**Symptoms**: Commands fail with authorization errors
**Solutions**:
```bash
# Check Polkit policies
pkaction --action org.projectatomic.aptostree.status

# Verify policy installation
dpkg -l | grep apt-ostree

# Check user session
loginctl show-user $USER

# Reinstall Polkit policies
sudo apt install --reinstall apt-ostree-polkit
```

#### **User Permission Issues**
**Symptoms**: User cannot perform authorized operations
**Solutions**:
```bash
# Check user groups
groups $USER

# Verify sudo access
sudo -l

# Check Polkit configuration
cat /etc/polkit-1/rules.d/50-apt-ostree.rules

# Add user to appropriate groups
sudo usermod -a -G sudo $USER
```

## 📝 **Logging and Debugging**

### **Enable Debug Logging**
```bash
# Set debug environment
export RUST_LOG=debug
export RUST_BACKTRACE=1

# Run with debug output
apt-ostree --debug <command>

# Check system logs
journalctl -u aptostreed -f --since "1 hour ago"
```

### **Collect Debug Information**
```bash
# Collect system information
apt-ostree status --json > status.json
ostree admin status > ostree-status.txt
systemctl status aptostreed > daemon-status.txt

# Check configuration files
ls -la /etc/apt-ostree/
cat /etc/apt-ostree/config.toml

# Verify installation
dpkg -l | grep apt-ostree
```

## 🆘 **Getting Additional Help**

### **When to Seek Help**
- **System won't boot** after apt-ostree operations
- **Daemon won't start** or respond to commands
- **Package operations fail** consistently
- **Performance issues** that persist after troubleshooting

### **Information to Collect**
```bash
# System information
uname -a
cat /etc/os-release
apt-ostree --version

# Status information
apt-ostree status --json
ostree admin status
systemctl status aptostreed

# Log files
journalctl -u aptostreed --since "1 day ago" > daemon-logs.txt
journalctl --since "1 day ago" | grep apt-ostree > system-logs.txt

# Configuration files
ls -la /etc/apt-ostree/
cat /etc/apt-ostree/config.toml
```

### **Where to Get Help**
- **Architecture Documents**: Check relevant architecture documents
- **Implementation Guides**: Review development and deployment guides
- **Community Support**: Report issues and seek community help
- **Development Team**: Contact the development team for critical issues

---

*This troubleshooting guide covers common issues and solutions. For detailed architecture information and implementation details, refer to the documents in the `docs/apt-ostree-daemon-plan/architecture/` directory.*