Troubleshooting¶
Having issues with AAM? This section provides solutions to common problems and guidance for getting help.
Quick Diagnostic¶
Run the built-in diagnostic tool:
This checks:
- AAM installation and version
- Python environment
- Registry configuration
- Platform detection
- Installed packages
- Configuration validity
Common Issues¶
Common Issues¶
Solutions to frequently encountered problems:
- Installation failures
- Package not found errors
- Deployment issues
- Permission denied errors
- Network connectivity problems
- Platform-specific issues
FAQ¶
Frequently asked questions about AAM:
- General concepts
- Package management
- Platform support
- Registry usage
- Security and signing
- Performance and optimization
Migration Guide¶
Guidance for migrating:
- From manual skill management to AAM
- Between AAM versions
- Between registry types
- From unscoped to scoped packages
- Between platforms
Getting Help¶
Check Documentation¶
- Search this documentation
- Review relevant concept pages
- Check platform-specific guides
- Read CLI command reference
Run Diagnostics¶
# Environment check
aam doctor
# Verify configuration
aam config list
# Check installed packages
aam list
# Test registry connectivity
aam search test
Enable Debug Logging¶
# Run commands with debug output
aam --debug install @author/my-package
# Or enable globally
aam config set debug true
Community Support¶
- GitHub Issues: https://github.com/spazyCZ/agent-package-manager/issues
- Discussions: https://github.com/spazyCZ/agent-package-manager/discussions
- Discord: [Coming soon]
Reporting Bugs¶
When reporting bugs, include:
- AAM version:
aam --version - Platform:
uname -a(Linux/macOS) or OS version (Windows) - Python version:
python --version - Full command: The command you ran
- Error output: Complete error message with
--debugflag - Doctor output: Output of
aam doctor
Example bug report:
### Environment
- AAM version: 0.1.0
- Platform: Ubuntu 22.04
- Python: 3.11.5
### Command
aam install @author/my-package --debug
### Error
[Full error output here]
### Doctor Output
[Output of aam doctor]
### Expected Behavior
Package should install successfully
### Actual Behavior
Installation fails with...
Debug Checklist¶
Before asking for help, try:
- Run
aam doctor - Check AAM version is latest:
pip install --upgrade aam - Verify registry configuration:
aam registry list - Test with
--debugflag - Check for similar issues on GitHub
- Review relevant documentation
- Try with a minimal example
Emergency Fixes¶
Complete Reset¶
If nothing works, reset AAM:
# Backup your packages first!
cp -r .aam .aam.backup
# Remove all AAM data
rm -rf ~/.aam
rm -rf .aam
# Reinstall AAM
pip uninstall aam
pip install aam
# Reconfigure
aam config set default_platform cursor
aam registry add <your-registry> --default
Package Corruption¶
# Verify package integrity
aam verify @author/my-package
# Force reinstall
aam install @author/my-package --force
# If that fails, remove and reinstall
aam uninstall @author/my-package
aam install @author/my-package
Configuration Issues¶
# Check current configuration
aam config list
# Reset configuration to defaults
rm ~/.aam/config.yaml
aam config set default_platform cursor
# Or manually edit
nano ~/.aam/config.yaml
Platform-Specific Issues¶
Cursor Issues¶
Claude Desktop Issues¶
GitHub Copilot Issues¶
Codex Issues¶
Advanced Topics¶
Registry Issues¶
See HTTP Registry Troubleshooting
Signing Issues¶
See Package Signing Troubleshooting
Performance Issues¶
- Check available disk space
- Verify network connectivity
- Clear package cache:
rm -rf ~/.aam/cache - Use local registry for faster installs
Still Need Help?¶
If you've tried everything and still have issues:
- Search GitHub issues: https://github.com/spazyCZ/agent-package-manager/issues
- Ask in Discussions: https://github.com/spazyCZ/agent-package-manager/discussions
- File a bug report with full details
We're here to help!
Next Steps¶
- Common Issues - Specific problem solutions
- FAQ - Frequently asked questions
- Migration Guide - Version and platform migration