Goal
Create docs/troubleshooting.md covering the most common operational issues users encounter, with concrete diagnostic commands and resolutions.
Files
internal/config/config.go (read for config error sources)
input/chainsync/plugin.go (read for connection error sources)
output/webhook/webhook.go (read for webhook delivery errors)
output/push/ (read for FCM error sources)
docs/troubleshooting.md (new)
Changes
Create docs/troubleshooting.md with sections:
- Connection issues: cannot reach Cardano node, network selection mismatch, socket path problems, NtC vs NtN selection.
- Configuration issues: env var not loading, YAML file not found, invalid value, precedence confusion (CLI > YAML > env).
- Filter issues: events not passing filter, address format requirements (bech32), policy ID format (28-byte hex), DRep format (bech32 or hex with optional CIP-0129 header byte).
- Push notification issues: FCM credentials, token registration, delivery failure modes.
- Webhook issues: delivery retries, timeouts, TLS certificate problems.
- Common error messages: list of error strings with the typical root cause and resolution. Pull the actual strings from the source files referenced above.
Each section should include at least one diagnostic command (curl, log inspection, etc.) where applicable.
Verification
- File renders on GitHub.
- Error message strings match the actual code (no stale or invented messages).
Dependencies
None.
Goal
Create
docs/troubleshooting.mdcovering the most common operational issues users encounter, with concrete diagnostic commands and resolutions.Files
internal/config/config.go(read for config error sources)input/chainsync/plugin.go(read for connection error sources)output/webhook/webhook.go(read for webhook delivery errors)output/push/(read for FCM error sources)docs/troubleshooting.md(new)Changes
Create
docs/troubleshooting.mdwith sections:Each section should include at least one diagnostic command (curl, log inspection, etc.) where applicable.
Verification
Dependencies
None.