{"id":"2adfbaff897e232e","repo":"sidorares/node-mysql2","slug":"callback-function-is-not-available-with-promise-cl","errorCode":null,"errorMessage":"Callback function is not available with promise clients.","messagePattern":"Callback function is not available with promise clients\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/promise/connection.js","lineNumber":35,"sourceCode":"    this.Promise = promiseImpl || Promise;\n    inheritEvents(connection, this, [\n      'error',\n      'drain',\n      'connect',\n      'end',\n      'enqueue',\n    ]);\n  }\n\n  release() {\n    this.connection.release();\n  }\n\n  query(query, params) {\n    const c = this.connection;\n    const stackHolder = captureStackHolder(PromiseConnection.prototype.query);\n    if (typeof params === 'function') {\n      throw new Error(\n        'Callback function is not available with promise clients.'\n      );\n    }\n    return new this.Promise((resolve, reject) => {\n      const done = makeDoneCb(resolve, reject, stackHolder);\n      if (params !== undefined) {\n        c.query(query, params, done);\n      } else {\n        c.query(query, done);\n      }\n    });\n  }\n\n  execute(query, params) {\n    const c = this.connection;\n    const stackHolder = captureStackHolder(PromiseConnection.prototype.execute);\n    if (typeof params === 'function') {\n      throw new Error(","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/sidorares/node-mysql2/blob/5ebe8903d6aea2d8ea1490e11b52491526e50f19/lib/promise/connection.js#L17-L53","documentation":"PromiseConnection.query() inspects its second argument and throws synchronously if it is a function. The promise API intentionally removes the callback signature of the callback API: a query returns a Promise and cannot accept a node-style callback. Passing (sql, cb) or (sql, params, cb) hits the typeof === 'function' check at connection.js:34 and throws before a Promise is constructed.","triggerScenarios":"Calling const res = conn.promise().query('SELECT 1', (err, rows) => {}), or migrating callback-style code to the promise API without removing the callback argument, or passing a function as the params argument by mistake.","commonSituations":"Refactoring from callback API to promise API and forgetting to drop the callback, mixing code styles in a migration, or accidentally passing a comparator/iterator function where params were expected.","solutions":["Drop the callback and await the returned promise: const [rows] = await conn.query('SELECT 1')","Pass params as an array, not a function: await conn.query('SELECT ? FROM t', [col])","If you need callback semantics, use the non-promise connection (omit .promise())","Use try/catch around await to handle errors instead of an error-first callback"],"exampleFix":"// before\nconn.promise().query('SELECT 1', (err, rows) => { /* never runs */ });\n\n// after\nconst [rows] = await conn.promise().query('SELECT 1');","handlingStrategy":"type-guard","validationCode":"function promiseQuery(conn, sql, params) {\n  if (typeof params === 'function') {\n    throw new TypeError('mysql2 promise API: do not pass a callback to query(); await the result');\n  }\n  return params !== undefined ? conn.query(sql, params) : conn.query(sql);\n}","typeGuard":"function isCallbackArg(arg) {\n  return typeof arg === 'function';\n}","tryCatchPattern":"try {\n  const [rows] = await conn.promise().query('SELECT 1');\n} catch (err) {\n  // note: this specific error throws synchronously, so the try must wrap the call itself\n  console.error(err);\n}","preventionTips":["Use mysql2/promise at the import site so the whole codebase is consistently promise-based","Never mix require('mysql2') and require('mysql2/promise') for the same connection","When migrating callback code, delete callback args as a separate commit step and run a typecheck"],"tags":["promise-api","callback","api-misuse","migration"],"analyzedSha":"5ebe8903d6aea2d8ea1490e11b52491526e50f19","analyzedAt":"2026-08-03T18:58:53.602Z","schemaVersion":2}