bird-troubleshooting

BIRD Troubleshooting

Determine whether the failure is discovery, static analysis, native parsing, runtime state, environment, or an upstream implementation defect.

Safety

• Start read-only. Do not reload, reconfigure, restart, kill, or attach a debugger to production BIRD without explicit authorization.
• Redact passwords, peer IPs, private ASNs, communities, socket paths, and policy details before sharing output.
• Treat custom validateCommand values and workspace scripts as executable code. Show them before running in an untrusted checkout.
• Preserve exact error text and timestamps, but do not dump whole production configs or logs.

Workflow

1. Run:

   uv run scripts/collect_diagnostics.py --root .
   

   Read references/troubleshooting-workflow.md for interpretation.

2. Establish BIRD version/build, selected config entry, project config, binary paths, the exact failing command, and last known good state.

3. Reproduce at the narrowest read-only layer:

   • discovery → birdcc init . --dry-run --json;
   • static/cross-file → birdcc lint <entry> --json;
   • native parse → matching bird -p -c <entry>;
   • live state → user-approved read-only birdc show ... commands.

4. If lint fails, route the fix through bird-agent. If lint succeeds but native parse fails, compare binary version, includes, generated inputs, permissions, and environment.

5. If parsing succeeds but runtime behavior is wrong, correlate logs and live state before using bird-source-explorer on the matching source revision.

6. Present ranked hypotheses with evidence, a falsifying check, and operational risk for each.

Completion

Confirm:

• baseline evidence and exact versions were collected;
• static, native-parse, and runtime layers were not conflated;
• the leading cause has direct evidence or is labeled a hypothesis;
• the next command is read-only or explicitly marked as mutating;
• secrets were not exposed;
• rollback or recovery impact is stated before any proposed operational change.