What causes "SASL: text must be a string" in brianc/node-postgres?

Reinstall node-postgres cleanly — this guard is internal and should never fire in normal operation.

brianc/node-postgres · error · TypeError

SASL: text must be a string

Error message

SASL: text must be a string

What it means

A TypeError thrown by isPrintableChars() when its text argument is not a string. This function validates that the server's nonce contains only printable ASCII characters per RFC 5802. In normal flow it is only called from parseServerFirstMessage() with the nonce extracted from parseAttributePairs(), which always yields string values — so this guard is effectively unreachable through standard pg usage.

Source

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

    throw new Error('SASL: SCRAM-SERVER-FINAL-MESSAGE: serverData must be a string')
  }

  const { serverSignature } = parseServerFinalMessage(serverData)

  if (serverSignature !== session.serverSignature) {
    throw new Error('SASL: SCRAM-SERVER-FINAL-MESSAGE: server signature does not match')
  }
}

/**
 * printable       = %x21-2B / %x2D-7E
 *                   ;; Printable ASCII except ",".
 *                   ;; Note that any "printable" is also
 *                   ;; a valid "value".
 */
function isPrintableChars(text) {
  if (typeof text !== 'string') {
    throw new TypeError('SASL: text must be a string')
  }
  return text
    .split('')
    .map((_, i) => text.charCodeAt(i))
    .every((c) => (c >= 0x21 && c <= 0x2b) || (c >= 0x2d && c <= 0x7e))
}

/**
 * base64-char     = ALPHA / DIGIT / "/" / "+"
 *
 * base64-4        = 4base64-char
 *
 * base64-3        = 3base64-char "="
 *
 * base64-2        = 2base64-char "=="
 *
 * base64          = *base64-4 [base64-3 / base64-2]
 */

View on GitHub (pinned to ff9d775abd)

Solutions

Reinstall node-postgres cleanly — this guard is internal and should never fire in normal operation.
Audit any monkeypatches or forks of the crypto/sasl.js module.
If writing tests that exercise SASL internals directly, ensure all string arguments are actual strings.

Defensive patterns

Strategy: try-catch

Try / catch

// Unreachable in normal operation — wrap connect() as a general safety net
try { await client.connect() } catch (e) { /* log and surface connection error */ }

Prevention

Use stock node-postgres without modifying internal SASL functions.
Reinstall pg if you suspect a corrupted or modified installation.

When it happens

Trigger: isPrintableChars() is called at sasl.js:198 with attrPairs.get('r'). Since parseAttributePairs() splits a string and returns a Map of string-to-string pairs, the nonce is always a string when reached through the normal code path. This TypeError only fires if the function is called directly with a non-string (e.g., from a custom fork or test).

Common situations: Practically unreachable with stock node-postgres. Would require a modified installation, a monkeypatched parseAttributePairs that returns non-string values, or a direct call to the unexported isPrintableChars function.

Related errors

AI-assisted analysis of brianc/node-postgres@ff9d775abd (2026-08-11). Data as JSON: /api/errors/1c1075d7f5b53c52. Report an issue: GitHub.