PHP error guide

MySQL server has gone away: meaning and fix

error sqlstate Affects: PDO with MySQL/MariaDB; exact server wording varies Last verified:

Error summary

Measure idle lifetime and packet size, reconnect at transaction boundaries, and avoid stale pooled handles. The server closes an established connection before the next command.

What it means

Measure idle lifetime and packet size, reconnect at transaction boundaries, and avoid stale pooled handles. The server closes an established connection before the next command.

What the error means

This message means that the server closes an established connection before the next command. The exact signature distinguishes mysql server has gone away from a generic application failure.

Why PHP produces it

The engine or service reports “MySQL server has gone away” because its required precondition was not met. Measure idle lifetime and packet size, reconnect at transaction boundaries, and avoid stale pooled handles.

PHP version notes

The mysql server has gone away wording here is based on PDO with MySQL/MariaDB; exact server wording varies; punctuation and exception class names can differ on older branches or vendor builds.

Most common causes

  • The immediate input or configuration reaches the specific condition: the server closes an established connection before the next command
  • The code path assumes the prerequisite for mysql server has gone away has already been satisfied.
  • For mysql server has gone away, development and production differ in version, extension, permissions, paths, or service configuration.
  • An earlier operation returned an unchecked value that is consumed by the line reporting mysql server has gone away.

Minimal examples

BAD — reproduces the problem

php 
$pdo->query($sqlAfterHoursIdle);

FIXED — safer pattern

php 
$pdo = connectDatabase();
$pdo->query($sql);

Step-by-step diagnosis

  1. Copy the complete “SQLSTATE[HY000]: General error: 2006 MySQL server has gone away” text and retain the first application stack frame.
  2. Reproduce mysql server has gone away in the same SAPI and environment listed for this page.
  3. Before changing mysql server has gone away, inspect the preceding value or directive and verify its type, path, version, and permissions.
  4. Apply the narrow correction—measure idle lifetime and packet size, reconnect at transaction boundaries, and avoid stale pooled handles—then repeat the original request once.

Fixes

Correct the failing prerequisite

Measure idle lifetime and packet size, reconnect at transaction boundaries, and avoid stale pooled handles

php 
$pdo = connectDatabase();
$pdo->query($sql);

Fail explicitly at the boundary

Validate the condition before the operation that emits mysql server has gone away, and log a safe diagnostic without credentials or full production paths.

Common mistakes when fixing it

  • Suppressing mysql server has gone away instead of correcting its upstream condition.
  • Testing mysql server has gone away only with the CLI binary when the failing request runs under FPM or Apache.
  • Changing a global setting for mysql server has gone away before confirming the site-specific effective configuration.

How to prevent it

  • Add a focused test that exercises the boundary responsible for mysql server has gone away.
  • Keep runtime versions, extensions, configuration, and deploy artifacts affecting mysql server has gone away reproducible.
  • Validate external data and service return values before they can trigger mysql server has gone away.

Web server / environment notes

fpm, cli, docker, linux. The failure occurs where the server closes an established connection before the next command

Tags: fpm,cli,docker,linux

Categories