Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

The mysql package says it cannot enqueue a Handshake after quit

ErrorError: Cannot enqueue Handshake after invoking quit.

Short answer

The message means connection.end() was already called on that connection object, and something later tried to use or connect it again. A connection that has quit cannot be reconnected. Use a pool for an Express app, or create a new connection for each unit of work and end it only when that work is done.

  • Applies to mysql npm package, Express 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Search the code for end() and connect() on the same variable. If a module-level connection is created once and a request handler calls end(), the second request fails.

    grep -rn "\.end()\|\.connect(\|createConnection" src/ app.js server.js 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The first request works, and every later request fails with this messageA shared connection is ended inside a route and then reusedFix
    2. 2A one-off script or job fails at its end, often when queries are started from callbacks or inside a loopA script ends the connection while queries are still being startedFix

What does the error look like?

  • Error: Cannot enqueue Handshake after invoking quit.
  • code: 'PROTOCOL_ENQUEUE_AFTER_QUIT'

Cause 1 of 2

A shared connection is ended inside a route and then reused

1Check

end() queues a quit packet after all earlier queries have run. After that the object is finished, and the README says a connection is re-connected only by establishing a new connection.

grep -rn "connection.end" src/

2Fix

Do not call end() per request. For a web server, use a pool: pool.query gets a connection, runs the query and releases it for you.

const mysql = require('mysql');
const pool = mysql.createPool({
  connectionLimit: 10,
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
});

app.get('/users', (req, res) => {
  pool.query('SELECT id, name FROM users', (err, rows) => {
    if (err) return res.status(500).json({ error: 'db' });
    res.json(rows);
  });
});

3Verify

Request the route several times in a row. Every call returns rows.

for i in 1 2 3; do curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/users; done

Confirmed by github.com

Did this fix it?

Cause 2 of 2

A script ends the connection while queries are still being started

1Check

end() lets queries already queued finish, but a query issued after the quit was queued is refused. Calling end() right after starting a loop of callback queries is the usual way to run into this.

grep -rn -B3 "\.end(" scripts/ jobs/ 2>/dev/null

2Fix

Call end() from the callback of the last query, or run the queries in order and end the connection once everything has finished.

const conn = mysql.createConnection(config);
conn.connect();
conn.query('SELECT 1 + 1 AS two', (err, rows) => {
  if (err) throw err;
  console.log(rows[0].two);
  conn.end();
});

3Verify

The script prints the result and exits without the error.

node scripts/job.js

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Create the pool once at start-up and export it, instead of building connections in handlers.
  • Call pool.end() only in a shutdown handler, after the server stopped accepting requests.
  • Handle the error argument in every callback, so a failing query is reported where it happens.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.