node-postgres: SCRAM-SERVER-FIRST-MESSAGE client password must be a string
Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a stringShort 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.
Fix it fast
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)2Match what you see, then jump to its fix
- 1
typeof 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
typeof prints number, for example a numeric password from a JSON or YAML config file.The password is a number, not a stringFix - 3
You pass password as a function.A password callback returns something other than a stringFix - 4
The message ends in non-empty string, and the variable is defined but its length is 0.The password is an empty stringFix
- 1
What does the error look like?
Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a stringSASL: 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
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
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
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 .env2Fix
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
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
Back end
Knex runs out of connections and the query waits until it times out
Knex: Timeout acquiring a connection. The pool is probably full. Are you missing a .transacting(trx) call?
Every query needs a free connection from Knex's pool.
3 causes, each with a fixBack end
Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production
at TCPConnectWrap.afterConnect [as oncomplete]
ETIMEDOUT means the other side never answered the connection attempt.
3 causes, each with a fixBack end
node-postgres pool times out waiting for a client
Error: timeout exceeded when trying to connect
The pool has no free client to give you.
2 causes, each with a fixBack end
PostgreSQL error: bind message has N parameter formats but 0 parameters
QueryFailedError: bind message has N parameter formats but 0 parameters
One query is carrying more bound values than the Postgres protocol can describe.
2 causes, each with a fixBack end
Node.js gets 'no pg_hba.conf entry for host' from PostgreSQL
error: no pg_hba.conf entry for host
The server found no pg_hba.conf rule matching your connection type, address, database and user, so it denied access.
3 causes, each with a fixBack end
Prisma Client fails with Invalid prisma.user.findUnique() invocation
The table `{table}` does not exist in the current database.
The first line, Invalid prisma.user.findUnique() invocation, only says which call failed.
4 causes, each with a fix