Solution skill
Supabase CLI: failed SASL auth (invalid SCRAM server-final-message received from server)
Complete solution
Fixes the Supabase CLI failing with failed SASL auth (invalid SCRAM server-final-message received from server) on db push/pull. Use when pooler connections fail while direct connections work, or right after a password change or special-character password. Switches to the direct connection or URL-encodes the password. Not for plain wrong-password errors or network timeouts.
Supabase CLI: failed SASL auth (invalid SCRAM server-final-message received from server)
TL;DR: the SCRAM handshake is breaking, which usually means the connection is going through the pooler (Supavisor) in the wrong mode, or the password has special characters that were not URL-encoded in the connection string. Use the direct database connection instead of the pooler URL for db push/pull, or re-encode the password. If you changed the DB password recently, update the stored password everywhere the CLI reads it.
failed SASL auth (invalid SCRAM server-final-message received from server)Steps
- Find which connection string the CLI uses: check for a pooler host (port 6543) vs the direct host (port 5432). Switch db push/pull to the direct connection string.
- If the password contains characters like @, #, %, or /, URL-encode them in the connection string. Expected: the SASL error disappears on the next attempt.
- If you recently reset the database password, update it in the CLI config and in any stored connection string, then retry.
- Still failing: confirm the plain password works via the dashboard SQL editor. If it works there, the issue is the connection string, not the credential.
When this applies
- the exact
failed SASL auth (invalid SCRAM server-final-message received from server)message - db push / db pull failing right after a password reset or when the password has special characters
- pooler (port 6543) connections failing while direct (port 5432) works
When it doesn't
password authentication failed for user postgres— the password itself is wrong, fix that first- connection timeouts / DNS failures reaching the host
- RLS or permission errors after connecting successfully
Compatibility
Supabase CLI db push/pull; Supavisor pooler (transaction/session modes) and direct Postgres connections. Verified against the Supabase CLI troubleshooting docs.
Variant phrasings
- supabase failed SASL auth invalid SCRAM
- supabase cli scram server final message
- supabase pooler SASL auth failed fix
Root cause
SCRAM authentication hashes the password on both sides; if the client sends a password mangled by URL parsing (unencoded special chars) or talks SCRAM to an endpoint expecting a different flow, the server's final message does not verify and the handshake aborts.
Edge cases
- transaction-mode pooler plus prepared statements is a separate failure class; use session mode for migrations
- passwords changed in the dashboard take a moment to propagate; retry before rebuilding strings
- storing the raw connection string in shell history leaks the password; prefer env files with tight perms
Evidence
Supabase CLI db push/pull can fail with failed SASL auth (invalid SCRAM server-final-message received from server) when the connection goes through the Supavisor pooler in the wrong mode, or when special characters in the password are not URL-encoded in the connection string. The verified fix from the Supabase troubleshooting docs: use the direct connection (port 5432) for migrations, URL-encode the password, and update stored credentials after a password reset. Source: https://supabase.com/docs/guides/troubleshooting/supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_CUzO2XtKFUEdDUISG_RULQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Supabase CLI: failed SASL auth (invalid SCRAM server-final-message received from server) <span>— Vectle</span></a>