What causes "Callback function is not available with promise clients." in sidorares/node-mysql2?

Await the result: const [rows] = await ns.query(sql).

sidorares/node-mysql2 · error · Error

Callback function is not available with promise clients.

Error message

Callback function is not available with promise clients.

What it means

PromisePoolNamespace.query() — the query method on a namespace obtained from poolCluster.of(pattern) in the promise API — throws synchronously when values is a function. The pool-cluster promise layer does not support callbacks; passing one signals API mixing.

Solutions

Await the result: const [rows] = await ns.query(sql).
Use the callback PoolCluster API (require('mysql2').createPoolCluster) if callbacks are required.
Catch the synchronous throw with try/catch around the call.

Example fix

// before
const ns = cluster.of('*');
ns.query('SELECT 1', (err, rows) => { /* ... */ });
// after
const ns = cluster.of('*');
const [rows] = await ns.query('SELECT 1');

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof values === 'function') {
  throw new TypeError('pool namespace query() in the promise API does not accept a callback; use await');
}

Type guard

function isPromisePoolNamespace(ns) {
  return ns != null && 'Promise' in ns && 'poolNamespace' in ns;
}

Try / catch

try {
  const [rows] = await ns.query(sql, values);
} catch (err) {
  if (/Callback function is not available/.test(err.message)) {
    // drop callback, use await
  } else {
    throw err;
  }
}

Prevention

Remember that poolCluster.of() returns a promise namespace; treat it like any promise client.
Document which cluster helpers are promise-based vs callback-based.
Migrate cluster code in one pass to avoid mixing patterns.

When it happens

Trigger: const cluster = createPoolCluster({}); cluster.add('node1', {...}); const ns = (await cluster).of('node1'); ns.query('SELECT 1', (err, rows) => {...}).

Common situations: Using pool clusters (multi-node/routed) and porting callback query code; helpers that wrap a namespace and forward a callback; copy-paste from callback cluster examples.

Related errors

AI-assisted analysis of sidorares/node-mysql2@8b1f829d37 (2026-08-11). Data as JSON: /api/errors/89f3486a692fd095. Report an issue: GitHub.

Appendix: source

Thrown at lib/promise/pool_cluster.js:32

    const corePoolNamespace = this.poolNamespace;
    return new this.Promise((resolve, reject) => {
      corePoolNamespace.getConnection((err, coreConnection) => {
        if (err) {
          reject(err);
        } else {
          resolve(new PromisePoolConnection(coreConnection, this.Promise));
        }
      });
    });
  }

  query(sql, values) {
    const corePoolNamespace = this.poolNamespace;
    const stackHolder = captureStackHolder(
      PromisePoolNamespace.prototype.query
    );
    if (typeof values === 'function') {
      throw new Error(
        'Callback function is not available with promise clients.'
      );
    }
    return new this.Promise((resolve, reject) => {
      const done = makeDoneCb(resolve, reject, stackHolder);
      corePoolNamespace.query(sql, values, done);
    });
  }

  execute(sql, values) {
    const corePoolNamespace = this.poolNamespace;
    const stackHolder = captureStackHolder(
      PromisePoolNamespace.prototype.execute
    );
    if (typeof values === 'function') {
      throw new Error(
        'Callback function is not available with promise clients.'
      );

View on GitHub (pinned to 8b1f829d37)