Troubleshoot Failing Runs

Troubleshoot Failing Runs

Use this sequence when hexi run fails or produces unexpected behavior.

1) Confirm environment and keys

hexi doctor

If API key source is none, resolve credentials first.

2) Validate plan independently

hexi plan-check --file examples/action_plans/mixed_step.json

For your own plan files, use the same command before execution.

3) Inspect runlog events

tail -n 120 .hexi/runlog.jsonl

Look for:

  • parse failures,
  • disallowed command errors,
  • path/write guard violations.

4) Replay deterministically

hexi apply --plan <plan.json> --task "debug replay"

This removes model variance from debugging.

5) Narrow task scope

Over-broad prompts increase plan ambiguity.

Prefer:

hexi run "Only update tests/test_parser.py; run pytest tests/test_parser.py"