{"record":{"id":"9563707f9a26077b","repo":"sidorares/node-mysql2","slug":"you-have-tried-to-call-then-catch-or-invok","errorCode":null,"errorMessage":"You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://sidorares.github.io/node-mysql2/docs#using-promise-wrapper, or the mysql2 documentation at https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper","messagePattern":"You have tried to call \\.then\\(\\), \\.catch\\(\\), or invoked await on the result of query that is not a promise, which is a programming error\\. Try calling con\\.promise\\(\\)\\.query\\(\\), or require\\('mysql2/promise'\\) instead of 'mysql2' for a promise-compatible version of the query interface\\. To learn how to use async/await or Promises check out documentation at https://sidorares\\.github\\.io/node-mysql2/docs#using-promise-wrapper, or the mysql2 documentation at https://sidorares\\.github\\.io/node-mysql2/docs/documentation/promise-wrapper","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/commands/query.js","lineNumber":49,"sourceCode":"    this.queryTimeout = null;\n    this._fieldCount = 0;\n    this._rowParser = null;\n    this._fields = [];\n    this._rows = [];\n    this._receivedFieldsCount = 0;\n    this._resultIndex = 0;\n    this._localStream = null;\n    this._unpipeStream = function () {};\n    this._streamFactory = options.infileStreamFactory;\n    this._connection = null;\n  }\n\n  then() {\n    const err =\n      \"You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://sidorares.github.io/node-mysql2/docs#using-promise-wrapper, or the mysql2 documentation at https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper\";\n\n    console.log(err);\n    throw new Error(err);\n  }\n\n  start(_packet, connection) {\n    if (connection.config.debug) {\n      console.log('        Sending query command: %s', this.sql);\n    }\n    this._connection = connection;\n    this.options = Object.assign({}, connection.config, this._queryOptions);\n    this._setTimeout();\n\n    const clientFlags =\n      connection.config.clientFlags & (connection.serverCapabilityFlags || 0);\n    const cmdPacket = new Packets.Query(\n      this.sql,\n      connection.config.charsetNumber,\n      this._queryOptions.attributes,\n      clientFlags\n    );","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/sidorares/node-mysql2/blob/8b1f829d3706404ab372cf97bd77ebcf86578d97/lib/commands/query.js#L31-L67","documentation":"The callback-mode Query object defines a then() trap (lib/commands/query.js:44-50) that logs and throws this message when the developer treats the return value of connection.query() as a thenable or awaits it. The callback API returns a Query (a EventEmitter/Readable stream), not a Promise; awaiting it is a programming error. The trap exists to produce a clear message instead of silent misbehavior.","triggerScenarios":"await connection.query(sql) on a callback-mode connection; const rows = await conn.query(sql) where conn came from require('mysql2'); chaining .then() on the Query object; using the callback API inside an async function and forgetting .promise().","commonSituations":"Mixing require('mysql2') and require('mysql2/promise') in the same codebase; copy-paste from a promise-style example into a callback-style connection; refactoring a callback handler to async/await without switching the API.","solutions":["Use the promise API: const conn = require('mysql2/promise').createConnection(...), then await conn.query(sql).","Or call the promise wrapper on an existing callback connection: await conn.promise().query(sql).","For streams, consume the Query as a Readable (query.on('result', ...)) instead of awaiting."],"exampleFix":"// before\nconst mysql = require('mysql2');\nconst conn = mysql.createConnection({});\nconst rows = await conn.query('SELECT 1'); // throws\n\n// after\nconst conn = require('mysql2/promise').createConnection({});\nconst [rows] = await conn.query('SELECT 1');","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// promise API: return value is a Promise\nimport type { Pool as PromisePool } from 'mysql2/promise';\nfunction isPromiseQuery<T>(r: Promise<[T]> | unknown): r is Promise<[T]> {\n  return r instanceof Promise;\n}","tryCatchPattern":null,"preventionTips":["Standardize one import path per codebase: either 'mysql2' (callback) or 'mysql2/promise'.","Always use .promise() on callback connections inside async functions.","Lint for await on non-Promise return values (typescriptAwaitThenableType)."],"tags":["promise","callback-api","api-usage","async-await"],"backgroundTag":null,"analyzedSha":"8b1f829d3706404ab372cf97bd77ebcf86578d97","analyzedAt":"2026-08-11T02:54:28.964Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}