13 / 13
Troubleshooting
Frequent issues: login, pooling, resume, staging, verification, webhooks
Cannot log in over plain HTTP
Production session cookies are Secure; browsers drop them on http:// —
logins appear to do nothing. Put TLS in front. SB_INSECURE_COOKIE=1 is for
local development only.
"Connection test failed" at registration
The console never shows the driver error (credential protection). Read the
redacted line in the server log: keyword_view gives host:port/db
(user, sslmode) — check reachability, credentials and TLS against it.
Supabase/Neon backups fail
Split by error class first. network → check reachability and pooled
endpoints (Supabase wants 5432/session, never 6543; Neon hosts must not
contain -pooler; the pre-flight and registration warnings exist exactly for
this). client_version is unrelated to pooling — it means no matching pg_dump
was found or clients are missing; fix it by installing the matching
postgresql-client major version. Changing host or port does not help.
An interrupted job never resumed
Resume runs only at startup (ResumeRemotePhase). Look for
resumed remote commit completed (success) or resume-related error/skip lines
after restart; their absence does not prove no attempt — resume only covers
jobs that are interrupted AND locally committed AND carry a remote intent
(uploading/committed) AND have a usable destination. Shutdowns before the
intent was recorded, local-only deployments and failed jobs are out of scope:
recover manually or wait for the next backup. The reclamation TTL counts from
finished_at, and startup resumes BEFORE pruning, so "over 72h means gone" is
not guaranteed.
Staging fills up / new backups fail with the disk class
Check supabackup_staging_bytes and destination health. Failed artifacts are
reclaimed after SB_FAILED_ARTIFACT_TTL_HOURS. In an emergency you may delete
staged ciphertext of failed jobs, but this is irreversible: an
upload-failure artifact still holds one complete successful export and may be
your only recoverable copy — failed jobs are not resumed at startup. Verify
job and artifact first, preserve valuable ciphertext plus its manifest
elsewhere, never delete by wildcard, and never treat the failed state itself
as a safe-delete signal (the succeeded anchor even less so).
Verification stays "not verified"
Verification is off by default (SB_VERIFY_ENABLED=false). Enabling it
requires SB_VERIFY_IDENTITY_FILE pointing at an age identity file that is a
regular, non-symlink file readable by the runtime user without group/other
permissions (0600 or 0400). Disk budget shortfalls settle as skipped with a
reason.
Webhooks receive nothing
Read the delivery log: a delivering row older than the 10s HTTP timeout
usually means crashes or unwritten results rather than a slow receiver — also
check the 15-minute delivery lease and startup recovery; dead means retries
are exhausted. "Send test" separates configuration problems from receiver
problems. Delivery is at-least-once — deduplicate on X-Supabackup-Event-ID.
Last updated