brianc/node-postgres · error · TypeError

Client was passed a null or undefined query

Error message

Client was passed a null or undefined query

What it means

Thrown synchronously (as a TypeError) by Client.prototype.query when the first argument (config) is null or undefined. The guard at client.js:631-633 uses a loose null check (config == null catches both null and undefined) because every query invocation requires at least a query config, text string, or Query object. Passing nothing or an explicitly null value means the caller has a logic error upstream.

Source

Thrown at packages/pg/lib/client.js:632

            activeQuery.handleError(queryError, this.connection)
            this.readyForQuery = true
            this._pulseQueryQueue()
          })
        }
      } else if (this.hasExecuted) {
        this._activeQuery = null
        this.emit('drain')
      }
    }
  }

  query(config, values, callback) {
    // can take in strings, config object or query object
    let query
    let result

    if (config == null) {
      throw new TypeError('Client was passed a null or undefined query')
    }

    if (typeof config.submit === 'function') {
      result = query = config
      if (!query.callback) {
        if (typeof values === 'function') {
          query.callback = values
        } else if (callback) {
          query.callback = callback
        }
      }
    } else {
      query = new Query(config, values, callback)
      if (!query.callback) {
        result = new this._Promise((resolve, reject) => {
          query.callback = (err, res) => (err ? reject(err) : resolve(res))
        }).catch((err) => {
          // replace the stack trace that leads to `TCP.onStreamRead` with one that leads back to the

View on GitHub (pinned to c5e8c9a57b)

Solutions

1. Ensure the query config/text argument is always a non-null value before calling client.query().
2. Add a default or guard: const sql = buildQuery() ?? 'SELECT 1'; client.query(sql).
3. If using TypeScript, enable strictNullChecks so the type system catches undefined at compile time.

Example fix

// before
const sql = maybeBuildQuery(); // may return undefined
await client.query(sql);

// after
const sql = maybeBuildQuery();
if (!sql) throw new Error('Query text is required');
await client.query(sql);

function safeQuery(client, config, values, callback) {
  if (config == null) {
    throw new TypeError('query config/text must not be null or undefined');
  }
  return client.query(config, values, callback);
}

function isValidQueryConfig(config) {
  return config != null && (typeof config === 'string' || typeof config === 'object');
}

// usage:
if (isValidQueryConfig(sql)) {
  client.query(sql);
}

try {
  await client.query(sql);
} catch (err) {
  if (err instanceof TypeError && /null or undefined query/i.test(err.message)) {
    console.error('Query was not built — check upstream logic');
  } else {
    throw err;
  }
}

When it happens

Trigger: client.query(null), client.query(undefined), or client.query(someVariable) where someVariable was never assigned. This throws synchronously in the calling stack frame, not as a rejected promise.

Common situations: A query string is built conditionally and the variable is undefined when the branch is skipped. A function parameter defaults to undefined and is forwarded to query(). Destructuring from an object where the text property is missing.

Related errors

• callback is not a function
• Client was passed a null or undefined query
• Both useLibpqCompat and uselibpqcompat are set. Please use o
• Invalid ${key}: ${value}
• Invalid sslnegotiation value: "${this.sslnegotiation}". Vali

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