sidorares/node-mysql2 · error · TypeError

Bind parameters must not contain undefined. To pass SQL NULL

Error message

Bind parameters must not contain undefined. To pass SQL NULL specify JS null

What it means

Connection.execute() iterates every element of the bind-values array and rejects `undefined`. SQL NULL must be expressed as the JS value `null`, not `undefined`, because `undefined` has no SQL representation and almost always indicates a missing or uninitialised value in application code. Catching this early prevents silent data corruption.

Source

Thrown at lib/base/connection.js:789

    }
    this._resolveNamedPlaceholders(options);
    // check for values containing undefined
    if (options.values) {
      //If namedPlaceholder is not enabled and object is passed as bind parameters
      if (!Array.isArray(options.values)) {
        throw new TypeError(
          'Bind parameters must be array if namedPlaceholders parameter is not enabled'
        );
      }
      options.values.forEach((val) => {
        //If namedPlaceholder is not enabled and object is passed as bind parameters
        if (!Array.isArray(options.values)) {
          throw new TypeError(
            'Bind parameters must be array if namedPlaceholders parameter is not enabled'
          );
        }
        if (val === undefined) {
          throw new TypeError(
            'Bind parameters must not contain undefined. To pass SQL NULL specify JS null'
          );
        }
        if (typeof val === 'function') {
          throw new TypeError(
            'Bind parameters must not contain function(s). To pass the body of a function as a string call .toString() first'
          );
        }
      });
    }
    const executeCommand = new Commands.Execute(options, cb);

    const prepareAndExecute = (errorCb) => {
      const prepareCommand = new Commands.Prepare(options, (err, stmt) => {
        if (err) {
          // skip execute command if prepare failed
          executeCommand.start = function () {
            return null;

View on GitHub (pinned to 5ebe8903d6)

Solutions

Coalesce undefined to null explicitly: `execute(sql, [id, value ?? null])`.
Find and fix the source of the undefined value in your parameter-building code.
Use a helper that maps undefined → null across the whole array before passing it.

Example fix

// before
connection.execute('INSERT INTO t(a,b) VALUES (?,?)', [a, req.body.b]);

// after
connection.execute('INSERT INTO t(a,b) VALUES (?,?)', [a, req.body.b ?? null]);

Defensive patterns

Strategy: validation

Validate before calling

function sanitizeBinds(values) {
  return values.map((v) => (v === undefined ? null : v));
}
conn.execute(sql, sanitizeBinds(rawValues));

Type guard

function hasNoUndefined(arr) {
  return Array.isArray(arr) && arr.every((v) => v !== undefined);
}

Prevention

Always coerce optional values with `?? null` before binding.
Add a unit test that asserts bind arrays contain no undefined.
Build bind arrays explicitly rather than via sparse spreads.

When it happens

Trigger: Passing a values array containing an `undefined` element: `execute(sql, [id, maybeUndefined, name])` where a variable was never assigned. Common with optional request parameters, sparse arrays, destructuring with missing keys, or `JSON.parse` producing objects whose `Object.values()` include undefined.

Common situations: An optional API field that was not provided (so the variable is undefined); array built via `[a, b, c]` where one variable shadowing was wrong; spreading an object's values where a property is absent; a bug in parameter assembly.

Related errors

AI-assisted analysis of sidorares/node-mysql2@5ebe8903d6 (2026-08-03). Data as JSON: /data/errors/0ce761b7718ee760.json. Report an issue: GitHub.