sidorares/node-mysql2 · critical · Error

no Promise implementation available.Use promise-enabled node

Error message

no Promise implementation available.Use promise-enabled node version or pass userland Promise implementation as parameter, for example: { Promise: require('bluebird') }

What it means

createConnectionPromise() in promise.js resolves the Promise implementation from opts.Promise || Promise and throws at promise.js:26 if the result is falsy. On any modern Node (>=0.12) the global Promise exists, so this only fires when the global has been polyfilled away to a falsy value AND no opts.Promise was supplied. The library cannot construct the returned promise without a Promise constructor.

Source

Thrown at promise.js:26

const createPool = require('./lib/create_pool.js');
const createPoolCluster = require('./lib/create_pool_cluster.js');
const PromiseConnection = require('./lib/promise/connection.js');
const PromisePool = require('./lib/promise/pool.js');
const {
  captureStackHolder,
  applyCapturedStack,
} = require('./lib/promise/capture_local_err.js');
const makeDoneCb = require('./lib/promise/make_done_cb.js');
const PromisePoolConnection = require('./lib/promise/pool_connection.js');
const inheritEvents = require('./lib/promise/inherit_events.js');
const PromisePoolNamespace = require('./lib/promise/pool_cluster');

function createConnectionPromise(opts) {
  const coreConnection = createConnection(opts);
  const stackHolder = captureStackHolder(createConnectionPromise);
  const thePromise = opts.Promise || Promise;
  if (!thePromise) {
    throw new Error(
      'no Promise implementation available.' +
        'Use promise-enabled node version or pass userland Promise' +
        " implementation as parameter, for example: { Promise: require('bluebird') }"
    );
  }
  return new thePromise((resolve, reject) => {
    coreConnection.once('connect', () => {
      resolve(new PromiseConnection(coreConnection, thePromise));
    });
    coreConnection.once('error', (err) => {
      applyCapturedStack(err, stackHolder);
      reject(err);
    });
  });
}

// note: the callback of "changeUser" is not called on success
// hence there is no possibility to call "resolve"

View on GitHub (pinned to 5ebe8903d6)

Solutions

1. Run on Node >= 14 (the project minimum), where global Promise always exists
2. Pass a Promise implementation in options: createConnection({ ..., Promise: require('bluebird') })
3. Ensure no code deletes or overwrites global Promise with a falsy value
4. If using a bundler/transpiler that mangles globals, alias global.Promise correctly

Example fix

// before
const conn = await mysql.createConnection({ host: 'localhost', user: 'root' }); // throws if global Promise is missing

// after
const conn = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  Promise: require('bluebird'), // explicit userland Promise
});

function ensurePromise(config) {
  const P = (config && config.Promise) || (typeof Promise !== 'undefined' ? Promise : null);
  if (!P) {
    throw new Error('No Promise implementation: pass { Promise: require("bluebird") } or upgrade Node');
  }
  return P;
}

function hasPromiseConstructor(config) {
  const P = (config && config.Promise) || (typeof Promise !== 'undefined' ? Promise : null);
  return typeof P === 'function';
}

When it happens

Trigger: Running on an ancient Node (<0.12) with no global Promise, explicitly deleting or shadowing global Promise in the process, or passing { Promise: null } / { Promise: false } in opts.

Common situations: Custom runtimes that strip globals, aggressive sandboxing, legacy embedded JS engines, or a config object that programmatically sets Promise to a falsy value. Extremely rare on supported Node versions.

Related errors

• "user" connection config property must be a string
• "database" connection config property must be a string
• Callback function is not available with promise clients.
• Callback function is not available with promise clients.
• Callback function is not available with promise clients.

AI-assisted analysis of sidorares/node-mysql2@5ebe8903d6 (2026-08-03). Data as JSON: /data/errors/57fb8aa4f99e06de.json. Report an issue: GitHub.