Guide
6 min read
Debugging Hook Failures
Troubleshoot common hook execution issues and learn best practices for reliable automation.
1
Common Failure Causes
Hooks fail for several reasons:
- Exit code non-zero: Tests failing, lint errors
- Timeout exceeded: Hook taking too long (60-120s limits)
- Missing dependencies: Commands not found
- Permission errors: File access issues
2
Reading Hook Output
The API returns hook output in the response:
``json``
{
"exit_code": 1,
"output": "Error: 3 tests failed...",
"duration_ms": 5432
}
Use this output to diagnose the issue.
3
Testing Hooks Locally
Test your hooks manually before relying on them:
``bash``
export TASK_IDENTIFIER="W1"
export TASK_TITLE="Test Task"
bash -c 'source .stride.md && echo $TASK_IDENTIFIER'
4
Best Practices
- Keep hooks fast (under 60 seconds)
- Use set -e to fail fast on errors
- Log meaningful output for debugging
- Handle edge cases (empty repos, missing files)
- Test hooks in CI before production
You're all set!
You've completed all the steps in this guide.