Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

node-postgres: SCRAM-SERVER-FIRST-MESSAGE client password must be a string

ErrorError: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string

Short answer

The server asked for SCRAM authentication and node-postgres had no string to hash. The password it received was undefined, null or a number. Print its type, then fix the source: load the .env file before the pool is created, set PGPASSWORD, or convert the value to a string.

  • Applies to node-postgres 8, PostgreSQL 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the type of the password that your code hands to the pool. It must say string.

    console.log(typeof process.env.DB_PASSWORD, process.env.DB_PASSWORD?.length)
  2. 2Match what you see, then jump to its fix

    1. 1typeof prints undefined, and the app works only on a machine where the variable is exported.The environment variable is undefined when the pool is createdFix
    2. 2typeof prints number, for example a numeric password from a JSON or YAML config file.The password is a number, not a stringFix
    3. 3You pass password as a function.A password callback returns something other than a stringFix
    4. 4The message ends in non-empty string, and the variable is defined but its length is 0.The password is an empty stringFix

What does the error look like?

  • Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string
  • SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a non-empty string

Cause 1 of 4

The environment variable is undefined when the pool is created

1Check

dotenv reads a file named .env from the current working directory by default. Import order matters: a module that creates the Pool before dotenv has run sees undefined.

ls -a | grep '^\.env'
node -e "require('dotenv').config(); console.log(typeof process.env.DB_PASSWORD)"

2Fix

Load dotenv first, or give it the path. node-postgres also reads PGPASSWORD when no password is passed in code.

import 'dotenv/config' // first import in the entry file
import { Pool } from 'pg'
const pool = new Pool({ password: process.env.DB_PASSWORD })

3Verify

Run a trivial query.

node -e "require('dotenv').config(); new (require('pg').Pool)({password: process.env.DB_PASSWORD}).query('select 1').then(r=>console.log(r.rows)).finally(()=>process.exit())"

Confirmed by github.com

Did this fix it?

Cause 2 of 4

The password is a number, not a string

1Check

The pg client checks the type of the password, so 12345 fails even though it looks right.

node -p "typeof require('./config.json').db.password"

2Fix

Quote the value in the config file, or convert it where you read it.

const pool = new Pool({ password: String(config.db.password) })

3Verify

Connect again.

node -e "require('./db').query('select 1').then(console.log)"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

A password callback returns something other than a string

1Check

node-postgres supports a synchronous or asynchronous callback for dynamic passwords, and it must resolve to a string.

grep -rn "password:" src/

2Fix

Make the callback return (or resolve to) a string, for example the token string, not an object.

const pool = new Pool({
  password: async () => (await getToken()).value,
})

3Verify

Run a query through the pool.

node -e "require('./db').query('select 1').then(console.log)"

Confirmed by node-postgres.com

Did this fix it?

Cause 4 of 4

The password is an empty string

1Check

A line such as DB_PASSWORD= in .env gives an empty string. The server stores no usable SCRAM secret for a role without a password.

grep DB_PASSWORD .env

2Fix

Set a real password on the role, then put the same value in the environment.

-- psql, as an admin
ALTER ROLE app_user WITH PASSWORD 'a-long-random-password';

3Verify

Connect with the new value.

PGPASSWORD='a-long-random-password' psql -h localhost -U app_user -d app -c 'select 1'

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Fail at start-up when a required variable is missing, before the Pool is created.
  • Keep passwords as quoted strings in every config format.
  • Load the environment in the first line of the entry file.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.