brianc/node-postgres · critical · Error

SASL: SCRAM-SERVER-FINAL-MESSAGE: server signature must be b

Error message

SASL: SCRAM-SERVER-FINAL-MESSAGE: server signature must be base64

What it means

Thrown when the `v=` (server signature) attribute is present in the final SASL message but fails the base64 format check at sasl.js:233 (isBase64 at line 172). Same root-cause family as the salt error (20) but on the final message.

Source

Thrown at packages/pg/lib/crypto/sasl.js:234

    nonce,
    salt,
    iteration,
  }
}

function parseServerFinalMessage(serverData) {
  const attrPairs = parseAttributePairs(serverData)
  const error = attrPairs.get('e')
  const serverSignature = attrPairs.get('v')

  if (error) {
    throw new Error(`SASL: SCRAM-SERVER-FINAL-MESSAGE: server returned error: "${error}"`)
  }

  if (!serverSignature) {
    throw new Error('SASL: SCRAM-SERVER-FINAL-MESSAGE: server signature is missing')
  } else if (!isBase64(serverSignature)) {
    throw new Error('SASL: SCRAM-SERVER-FINAL-MESSAGE: server signature must be base64')
  }
  return {
    serverSignature,
  }
}

function xorBuffers(a, b) {
  if (!Buffer.isBuffer(a)) {
    throw new TypeError('first argument must be a Buffer')
  }
  if (!Buffer.isBuffer(b)) {
    throw new TypeError('second argument must be a Buffer')
  }
  if (a.length !== b.length) {
    throw new Error('Buffer lengths must match')
  }
  if (a.length === 0) {
    throw new Error('Buffers cannot be empty')

View on GitHub (pinned to c5e8c9a57b)

Solutions

Connect directly to PostgreSQL bypassing any pooler/proxy.
Confirm pooler/proxy SCRAM-SHA-256 passthrough support.
Verify TLS integrity end-to-end.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await client.connect()
} catch (err) {
  if (/server signature must be base64/.test(err.message)) {
    logger.error('SCRAM final frame v= attribute was not base64 -- suspect intermediary', { err })
    return connectBypassingPooler()
  }
  throw err
}

Prevention

Terminate TLS directly at Postgres to avoid middlebox rewriting of SASL frames.
Pin pooler versions with correct SCRAM-SHA-256 passthrough.
Bypass the pooler when reproducing auth-layer errors.

When it happens

Trigger: finalizeSession receives a final frame whose `v=` value contains characters outside the base64 alphabet or has malformed padding, so it cannot be compared against session.serverSignature at line 139.

Common situations: Proxy/pooler corruption of the final SASL frame; non-conformant server emitting an unencoded signature.

Related errors

AI-assisted analysis of brianc/node-postgres@c5e8c9a57b (2026-08-03). Data as JSON: /data/errors/837da76b8d8f91a5.json. Report an issue: GitHub.