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

PromisePoolCluster.query() (the cluster-level query from 'mysql2/promise') throws synchronously when args is a function. The cluster promise wrapper routes queries across nodes and returns a promise; callbacks are not supported. Note this is the cluster itself, not a namespace obtained via .of().

Solutions

1. Await the result: const [rows] = await cluster.query(sql).
2. Use the callback PoolCluster API (require('mysql2').createPoolCluster) for callback patterns.
3. Wrap the call in try/catch to handle the synchronous throw.

Example fix

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

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

function isPromisePoolCluster(c) {
  return c != null && 'Promise' in c && 'poolCluster' in c;
}

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

When it happens

Trigger: const cluster = createPoolCluster({}); cluster.add('node1', {...}); cluster.query('SELECT 1', (err, rows) => {...}) using the promise cluster.

Common situations: Direct cluster queries (routed across nodes) ported from callback examples; helpers that accept a cluster and a callback; confusion between cluster.query and namespace.query.

Related errors

• Callback function is not available with promise clients.
• Callback function is not available with promise clients.
• Callback function is not available with promise clients.
• no Promise implementation available.Use promise-enabled…

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

Appendix: source

Thrown at promise.js:89

      corePoolCluster.getConnection(
        pattern,
        selector,
        (err, coreConnection) => {
          if (err) {
            reject(err);
          } else {
            resolve(new PromisePoolConnection(coreConnection, this.Promise));
          }
        }
      );
    });
  }

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

  execute(sql, args) {
    const corePoolCluster = this.poolCluster;
    const stackHolder = captureStackHolder(
      PromisePoolCluster.prototype.execute
    );
    if (typeof args === 'function') {
      throw new Error(
        'Callback function is not available with promise clients.'
      );

View on GitHub (pinned to 8b1f829d37)