apt-ostree/docs/apt-ostree-daemon-plan/reference/troubleshooting.md

🔧 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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.