Troubleshooting
When things go wrong, these guides help you get back on track.
Quick Links
| Issue | Guide |
|---|---|
| Claude Code crashed/froze | Emergency Recovery |
| Hook errors | Emergency Recovery |
| GitHub sync not working | Emergency Recovery |
| Status line wrong | Emergency Recovery |
Common Issues
"Claude Code Keeps Crashing"
Most crashes are due to context explosion. See the prevention strategies.
Quick fix:
export SPECWEAVE_DISABLE_HOOKS=1
rm -f .specweave/state/.hook-*
"Hooks Not Running"
Check if hooks are disabled:
echo $SPECWEAVE_DISABLE_HOOKS
# If "1", hooks are disabled
# Re-enable
unset SPECWEAVE_DISABLE_HOOKS
"Sync Throttled"
SpecWeave limits API calls to prevent rate limiting. Wait 60 seconds or use /specweave:sync-progress to force sync.
Getting Help
- Check this documentation
- Search GitHub Issues
- Report new issues with:
- SpecWeave version
- Node.js version
- Steps to reproduce
- Error messages