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

PromisePool.query() (pool.query from mysql2/promise) throws synchronously when args is a function. Pools in the promise API return a promise per query and cannot invoke a callback; passing one indicates the caller mixed the two APIs. Common because pools are often shared and one branch of code may still be callback-based.

Solutions

1. Await the result: const [rows] = await pool.query(sql).
2. Use the callback pool (require('mysql2').createPool) for callback-style code.
3. Search the codebase for `.query(.*, (` to find stray callbacks on promise pools.

Example fix

// before
const pool = createPool({ host: 'localhost' });
pool.query('SELECT 1', (err, rows) => { /* ... */ });
// after
const pool = createPool({ host: 'localhost' });
const [rows] = await pool.query('SELECT 1');

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

function isPromisePool(p) {
  return p != null && 'Promise' in p && 'pool' in p;
}

try {
  const [rows] = await pool.query(sql, args);
} catch (err) {
  if (/Callback function is not available/.test(err.message)) {
    // strip the callback and re-run as promise
  } else {
    throw err;
  }
}

When it happens

Trigger: const pool = createPool({...}); pool.query('SELECT 1', (err, rows) => {...}) where createPool came from 'mysql2/promise'.

Common situations: Shared pool across a codebase mid-migration; generic db helpers (db.query(sql, cb)) that were not updated; sample code copied from the callback docs.

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/377c7aba5e461e6c. Report an issue: GitHub.

Appendix: source

Thrown at lib/promise/pool.js:42

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

  releaseConnection(connection) {
    if (connection instanceof PromisePoolConnection) connection.release();
  }

  query(sql, args) {
    const corePool = this.pool;
    const stackHolder = captureStackHolder(PromisePool.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);
      if (args !== undefined) {
        corePool.query(sql, args, done);
      } else {
        corePool.query(sql, done);
      }
    });
  }

  execute(sql, args) {
    const corePool = this.pool;
    const stackHolder = captureStackHolder(PromisePool.prototype.execute);
    if (typeof args === 'function') {
      throw new Error(

View on GitHub (pinned to 8b1f829d37)