Troubleshooting Guide¶

Home > Troubleshooting

Ahoy, matey! Hit a snag? This be yer map to fix common issues and get back on course.

🚨 Start Here - Common Issues¶

CHECK THIS FIRST! Most problems have already been solved:

• Discoveries - Known issues and solutions (CHECK HERE FIRST!)

Quick Fixes by Category¶

Auto Mode Issues¶

• Auto Mode Permission Error - Permission denied errors in auto mode

Exit & Shutdown Issues¶

• Stop Hook Exit Hang - Fix 10-13 second hang on exit (resolved in v0.9.1)

Installation Issues¶

• Copytree Same-File Crash - Fix SameFileError when AMPLIHACK_HOME points at the source tree
• Copilot Installation False Negative - Installation reports failure when it actually succeeded

Startup Issues¶

• Startup Conflict Prompt - Fix "Uncommitted changes detected in .claude/" prompt on every startup

Configuration Problems¶

• Hook Configuration - Customize framework behavior
• Profile Management - Multi-environment configuration guidance

Azure & Cloud¶

• Azure Integration - Azure deployment issues

Documentation Issues¶

Having trouble with documentation?

• Documentation Guidelines - Writing effective docs
• Documentation Knowledge Graph - How docs connect

Development & Testing Issues¶

Problems during development?

Testing¶

• Benchmarking - Performance measurement
• Test Gap Analyzer - Find untested code

Code Quality¶

• Code Review Guide - Review process and standards
• Default Workflow - End-to-end checklist for finishing work
• CS Validator - Code style validation

Memory System Issues¶

Problems with agent memory?

• Memory System Docs - Complete memory documentation
• Memory Testing Strategy - Validate memory behavior and coverage
• Memory Code Review - Example troubleshooting

Security Issues¶

Security-related problems?

• Security Recommendations - Essential security practices
• Security Context Preservation - Maintain security through sessions
• Security Guides - Security-specific troubleshooting and guidance

Getting More Help¶

Still stuck? Here's what to do:

1. Check Discoveries - DISCOVERIES.md has most known issues
2. Search Documentation - Use the Documentation Graph
3. Review Patterns - Check Development Patterns
4. Ask for Help - GitHub Issues

Prevention Guides¶

Learn how to avoid common issues:

• Development Philosophy - Principles that prevent problems
• This Is The Way - Best practices and patterns
• Default Workflow - Ensure process compliance

Related Documentation¶

• Commands - Choose the right command
• Agents - Agent-specific issues
• Features - Feature troubleshooting

Pro Tip: Most issues are already documented in DISCOVERIES.md. Always check there first!