Skip to content

Troubleshooting Guide

Home > Troubleshooting Guide

This guide covers common issues, error messages, and solutions for AppImage Updater.

Getting Help

Command Usage Help

AppImage Updater provides helpful usage information when you run commands without required arguments:

# Get help for any command by running it without arguments
appimage-updater config     # Shows config command help
appimage-updater show       # Shows show command help
appimage-updater edit       # Shows edit command help
appimage-updater remove     # Shows remove command help

# Or use the traditional --help flag
appimage-updater config --help
appimage-updater --help     # Main help

This makes it easy to explore available options without needing to remember help flags.

Quick Diagnostics

Check System Status

# Run with debug output
appimage-updater --debug check --dry-run

# Verify configuration
appimage-updater list

# Check specific application
appimage-updater show MyApp

Common Debug Information

Look for these key indicators in debug output:

  • GitHub API authenticated: True/False
  • Rate limit remaining: X/5000 (authenticated) or X/60 (unauthenticated)
  • Pattern matching results: Found X assets
  • Download directory: Exists and writable

Installation Issues

Command Not Found

Error: appimage-updater: command not found

Solutions:

  1. Verify installation:
pip show appimage-updater
pipx list | grep appimage-updater
  1. Check PATH:
echo $PATH
which appimage-updater
  1. Reinstall with pipx (recommended):
pipx install appimage-updater
pipx ensurepath
  1. Add to PATH manually:
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Permission Denied

Error: Permission denied when running commands

Solutions:

  1. Check file permissions:
ls -la ~/.local/bin/appimage-updater
chmod +x ~/.local/bin/appimage-updater
  1. Verify directory permissions:
ls -la ~/.config/appimage-updater/
chmod 755 ~/.config/appimage-updater/

Configuration Issues

Config File Not Found

Error: Configuration file not found

Solutions:

  1. Run any command to create configuration automatically:
appimage-updater list

This will automatically create the configuration directory and files.

  1. Specify config location:
appimage-updater --config-dir ~/.config/appimage-updater check
  1. Manually create minimal config (if automatic creation fails):
mkdir -p ~/.config/appimage-updater/apps
echo '{"global_config": {"concurrent_downloads": 3, "timeout_seconds": 30}}' > ~/.config/appimage-updater/config.json

Invalid JSON Configuration

Error: JSON decode error or Invalid configuration

Solutions:

  1. Validate JSON syntax:
python -m json.tool ~/.config/appimage-updater/config.json

  1. Common JSON issues:

  2. Missing commas between objects

  3. Trailing commas (not allowed in JSON)
  4. Unescaped quotes in strings

  5. Missing closing brackets/braces

  6. Backup and regenerate:

Option A: Simple directory backup

# Backup entire configuration directory
cp -r ~/.config/appimage-updater ~/.config/appimage-updater.backup

# Remove problematic config and let it regenerate
rm -rf ~/.config/appimage-updater
appimage-updater list  # This will recreate the config automatically

Option B: Export configurations as commands (recommended)

# Export all application configurations as add commands
appimage-updater show --add-command > app-add-commands.sh

# Backup global configuration
appimage-updater config show --format json > config.json.backup

# Remove problematic application configs
rm ~/.config/appimage-updater/apps/*.json

# Restore applications by running the exported commands
bash ./app-add-commands.sh

# Restore global config settings manually if needed
# (Review config.json.backup and use 'appimage-updater config set' commands)

This approach is safer as it preserves your configuration as executable commands that can be version-controlled.

Application Not Found

Error: Application 'MyApp' not found

Solutions:

  1. List all applications:
appimage-updater list
  1. Check case sensitivity:
# Application names are case-insensitive
appimage-updater show freecad  # Works for "FreeCAD"
  1. Add missing application:
appimage-updater add MyApp https://github.com/user/app ~/Apps/MyApp

Network Issues

GitHub API Rate Limits

Error: API rate limit exceeded

Solutions:

  1. Set up GitHub authentication:
export GITHUB_TOKEN="your_token_here"
appimage-updater --debug check --dry-run
  1. Check current rate limit status:

This shows how many API requests you have remaining and when the limit resets:

# With authentication (shows limit of 5000/hour)
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit

# Without authentication (shows limit of 60/hour)
curl https://api.github.com/rate_limit

Look for "remaining" (requests left) and "reset" (Unix timestamp when limit resets) in the output.

  1. Wait for rate limit reset (shown in error message)

  2. Reduce check frequency temporarily

Connection Timeouts

Error: Connection timeout or Network error

Solutions:

  1. Increase global timeout:
appimage-updater config set timeout-seconds 120
  1. Check network connectivity:
curl -I https://api.github.com
ping github.com
  1. Configure proxy if needed:
export HTTPS_PROXY="http://proxy.example.com:8080"
  1. Check with debug mode for more details:
appimage-updater --debug check MyApp --dry-run

SSL Certificate Issues

Error: SSL certificate verification failed

Solutions:

  1. Update certificates:
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# CentOS/RHEL
sudo yum update ca-certificates
  1. Check system time:
date
sudo ntpdate -s time.nist.gov  # If time is wrong
  1. Verify GitHub connectivity:
openssl s_client -connect api.github.com:443 -servername api.github.com

Pattern Matching Issues

No Assets Match Pattern

Error: No assets match pattern: your-pattern

Common Causes:

  • Pattern doesn't match any assets in the latest release
  • Assets exist in older releases but not the most recent one
  • Nightly builds or continuous releases aren't the latest by date

Solutions:

  1. Check multiple releases (AppImage Updater now searches up to 20 releases automatically):
# View recent releases and their assets
curl -s https://api.github.com/repos/USER/REPO/releases?per_page=5 | \
  jq '.[] | {tag_name, assets: [.assets[].name]}'
  1. Test pattern with debug output:
appimage-updater --debug check MyApp --dry-run
  1. For nightly builds, ensure you're using --prerelease:
appimage-updater add --prerelease --pattern ".*nightly.*\.AppImage$" \
  MyApp https://github.com/user/app ~/Apps/MyApp
  1. Use custom pattern:
# For specific OS/architecture
appimage-updater add --pattern "(?i).*linux.*x86_64.*\.AppImage$" \
  MyApp https://github.com/user/app ~/Apps/MyApp

# For ZIP files
appimage-updater add --pattern "(?i).*linux.*\.zip$" \
  MyApp https://github.com/user/app ~/Apps/MyApp
  1. Common pattern examples:
# Case-insensitive AppImage
--pattern "(?i).*\.AppImage$"

# Specific architecture
--pattern "(?i).*x86_64.*\.AppImage$"

# Exclude specific terms
--pattern "(?i)(?!.*debug).*\.AppImage$"

# Multiple formats
--pattern "(?i).*(\.AppImage|\.zip)$"

Multiple Assets Matched

Error: Multiple assets matched pattern with interactive selection

Solutions:

  1. Use non-interactive mode:
appimage-updater check --no-interactive
  1. Refine pattern to be more specific:
# Too broad
--pattern "(?i).*\.AppImage$"

# More specific
--pattern "(?i)MyApp.*linux.*x86_64.*\.AppImage$"
  1. Check what's being matched:
appimage-updater --debug show MyApp

Download Issues

Download Directory Issues

Error: Download directory does not exist or Permission denied

Solutions:

  1. Create manually with correct permissions:
mkdir -p ~/Apps/MyApp
chmod 755 ~/Apps/MyApp
  1. Check parent directory permissions:
ls -la ~/Apps/
chmod 755 ~/Apps/

Checksum Verification Failed

Error: Checksum verification failed

Solutions:

  1. Check if checksums are available:
curl -s https://api.github.com/repos/USER/REPO/releases/latest | jq '.assets[] | select(.name | contains("SHA256"))'
  1. Disable checksum verification (not recommended):
appimage-updater edit MyApp --no-checksum
  1. Use different checksum algorithm:
appimage-updater edit MyApp --checksum-algorithm sha1
  1. Manual verification:
sha256sum ~/Apps/MyApp/downloaded_file.AppImage
# Compare with published checksum

Disk Space Issues

Error: No space left on device

Solutions:

  1. Check available space:
df -h ~/Apps/
  1. Clean old files (if rotation enabled):
appimage-updater edit MyApp --retain-count 2  # Keep fewer old versions
  1. Move to different location:
appimage-updater edit MyApp --download-dir /path/with/more/space

File Rotation Issues

Error: Failed to create symlink or symlink points to wrong file

Solutions:

  1. Check symlink status:
ls -la ~/bin/myapp.AppImage
readlink ~/bin/myapp.AppImage
  1. Remove broken symlink:
rm ~/bin/myapp.AppImage
appimage-updater check MyApp  # Recreates symlink
  1. Verify symlink path:
appimage-updater show MyApp  # Check symlink_path setting
  1. Update symlink path:
appimage-updater edit MyApp --symlink-path ~/bin/myapp.AppImage

Old Files Not Cleaned

Issue: Too many old versions accumulating

Solutions:

  1. Check retention setting:
appimage-updater show MyApp
  1. Adjust retention count:
appimage-updater edit MyApp --retain-count 3
  1. Manual cleanup:
# List files by date
ls -lt ~/Apps/MyApp/

# Remove old files manually (keep newest)
rm ~/Apps/MyApp/old_version.AppImage
rm ~/Apps/MyApp/old_version.AppImage.info

Version Detection Issues

Incorrect Version Comparison

Issue: Updates not detected or wrong version shown

Solutions:

  1. Check metadata files:
ls -la ~/Apps/MyApp/*.info
cat ~/Apps/MyApp/current_file.AppImage.info
  1. Create missing metadata:
echo "Version: v1.2.3" > ~/Apps/MyApp/current_file.AppImage.info
  1. Force update check:
appimage-updater check MyApp --dry-run
  1. Check GitHub release tags:
curl -s https://api.github.com/repos/USER/REPO/releases/latest | jq '.tag_name'

Performance Issues

Slow Update Checks

Issue: Update checks take too long

Solutions:

  1. Use parallel checking (if multiple apps):
# Built-in parallel processing for multiple apps
appimage-updater check
  1. Reduce global timeout for faster failure:
appimage-updater config set timeout-seconds 30
  1. Check specific apps only:
appimage-updater check MyApp
  1. Monitor rate limits:
appimage-updater --debug check --dry-run | grep -i rate

Reporting Issues

Enable Debug Mode

Always use debug mode when reporting issues:

appimage-updater --debug command-that-fails 2>&1 | tee debug.log

Collect System Information

# System info
uname -a
python --version
pip show appimage-updater

# Configuration
appimage-updater list
appimage-updater config show
cat ~/.config/appimage-updater/config.json  # Global config
ls -la ~/.config/appimage-updater/apps/     # Application configs

# Network connectivity
curl -I https://api.github.com

Report Issues

When reporting bugs, include:

  1. Debug output (with sensitive info removed)
  2. System information (OS, Python version)
  3. Configuration (sanitized)
  4. Steps to reproduce
  5. Expected vs actual behavior

Community Resources

Prevention Tips

Regular Maintenance

# Weekly health check
appimage-updater --debug check --dry-run

# Monthly configuration review
appimage-updater list

Best Practices

  • Use GitHub authentication to avoid rate limits
  • Enable checksum verification for security
  • Set reasonable timeouts for your network
  • Monitor disk space in download directories
  • Keep configuration backed up
  • Test with dry-run before making changes

Monitoring Setup

# Add to cron for daily checks
0 9 * * * appimage-updater check 2>&1 | logger -t appimage-updater

# Log rotation issues
0 10 * * * find ~/Apps -name "*.AppImage" -mtime +30 | wc -l