Troubleshooting

Match your symptom to the fix.

Find your symptom, apply the fix, follow the link for the full story.

The run fails before any check

Symptom: UNKNOWN / exit 3 on connect. Fix: check DSN resolution order, then confirm the server reports version 13–17 (SELECT current_setting('server_version_num') must be 130000–179999). Run pgdba config doctor to see exactly which profile fails and why. → connection profiles
Symptom: typo’d profile or config key. Fix: exit-3 messages include a did you mean: suggestion — trust it. The same machinery powers --explain-flag / --explain-term lookups.
Symptom: migration refused at preflight. Fix: read the remediation text after each mismatch (locale/encoding/extension/disk); use --force only to proceed past health/scope gates with warnings recorded. → the migrate safe lane

Symptom: slow queries show heuristic-unverified or a pg_stat_activity fallback. Fix: install pg_stat_statements (allowlisted) on the target. The check degrades gracefully until then, and every finding states its evidence quality.
Symptom: no writes with --apply. Fix: expected on RDS/replicas (refused per finding, see the audit log) or when remediation is multi-statement (stays dry-run for manual review). A non-TTY --apply without --yes is refused (exit 1) but the run still writes its report — exit 1 is the refusal signal; the report always describes the run that just happened. → apply remediation
Symptom: second serve start exits 3 naming a pid. Fix: another instance holds the state dir — stop it first. A stale pidfile (dead pid) is replaced automatically with a warning. → run as a service
Symptom: fleet check reports a target BROKEN. Fix: the per-target error is redacted but names the cause (usually connect refused / bad profile). Fix that target’s connection, re-run — other targets are unaffected. → run a fleet