Troubleshooting

• UNKNOWN / exit 3 on connect — check DSN resolution order (see profiles); verify 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.
• Slow queries show heuristic-unverified / pg_stat_activity fallback — install pg_stat_statements (allowlisted) on the target; the check degrades gracefully until then, and findings say their evidence quality.
• No writes with --apply — 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. See apply remediation.
• Migration refused at preflight — read the remediation text after each mismatch (locale/encoding/extension/disk); use --force only to proceed past health/scope gates with warnings recorded. See the migrate safe lane.
• Live-DB tests fail locally — integration tests need the pgdba-owned pgdba-dev-test container (docker compose -f devdb/compose.yaml up -d pg-test, port 5436; never a shared instance). PGDBA_TEST_DSN overrides the DSN.
• Typo’d profile or config key — exit-3 messages include a did you mean: suggestion; the same machinery powers --explain-flag/--explain-term lookups.