Maaz Zindani

Loading the index…

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

PHP stops with an uncaught mysqli_sql_exception and the MySQL message after it

ErrorFatal error: Uncaught mysqli_sql_exception: Unknown column 'email' in 'field list'

Short answer

The exception is only the messenger. Since PHP 8.1 mysqli throws it for every MySQL error, so the real problem is the message after it. Catch it, log getCode() and getMessage(), and match them to the cause below: bad SQL, wrong credentials or host, or data the column refuses.

  • Applies to PHP 8.3, MySQL 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Wrap the failing call in try/catch and write the MySQL error number, the SQLSTATE and the message to the log. The number tells you which cause below applies.

    try {
        $mysqli = new mysqli('localhost', 'app', 'secret', 'shop');
        $mysqli->query('SELECT email FROM users');
    } catch (mysqli_sql_exception $e) {
        error_log($e->getCode() . ' ' . $e->getSqlState() . ' ' . $e->getMessage());
    }
  2. 2Match what you see, then jump to its fix

    1. 1The site worked before a PHP upgrade, nothing in the code changed, and the fatal error now appears on a query that used to fail quietly.PHP 8.1 made mysqli throw, and old code never handled errorsFix
    2. 2Error 1054 Unknown column, 1146 Table doesn't exist, 1064 a syntax message ending in near ... at line N, or 1136 Column count doesn't match value count.The SQL names a column or table that does not exist, or is malformedFix
    3. 3Error 1045 Access denied, 1049 Unknown database, 2002 Can't connect to local MySQL server through socket, or 2003 Can't connect to MySQL server on host:port.The connection itself fails: wrong login, unknown database or no serverFix
    4. 4Error 1048 Column cannot be null, 1406 Data too long for column, 1366 Incorrect value for column, or 1062 Duplicate entry.The table refuses the data you try to saveFix

What does the error look like?

  • Fatal error: Uncaught mysqli_sql_exception: Unknown column 'email' in 'field list'
  • Fatal error: Uncaught mysqli_sql_exception: Table 'shop.orders' doesn't exist
  • Fatal error: Uncaught mysqli_sql_exception: Access denied for user 'app'@'localhost' (using password: YES)
  • Fatal error: Uncaught mysqli_sql_exception: Data too long for column 'name' at row 1

Cause 1 of 4

PHP 8.1 made mysqli throw, and old code never handled errors

1Check

Up to PHP 8.0 the default report mode was MYSQLI_REPORT_OFF, so mysqli stayed silent and a failed call just returned false. From 8.1 the default is MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT, which throws mysqli_sql_exception. Ask PHP whether the default is active.

php -r 'var_dump((new mysqli_driver)->report_mode === (MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT));'

2Fix

Keep exceptions on, and catch them where you can act on them (show a friendly page, roll back, retry). Fix the error behind them; hiding it is not a fix. Only if you cannot touch the code yet, restore the old behaviour with mysqli_report(MYSQLI_REPORT_OFF) at the start of the script.

try {
    $result = $mysqli->query($sql);
} catch (mysqli_sql_exception $e) {
    error_log($e->getMessage());
    http_response_code(500);
    exit('Something went wrong.');
}

3Verify

A failing query now writes one line to the error log and the visitor sees your message, not a stack trace.

tail -n 5 /path/to/your/php-error.log

Confirmed by php.net

Did this fix it?

Cause 2 of 4

The SQL names a column or table that does not exist, or is malformed

1Check

These four codes come from the statement, not from the connection. Compare every name in the query with the real schema, including the database you connected to.

SHOW TABLES;
DESCRIBE users;

2Fix

Correct the name or the syntax, or run the missing migration on this database. For 1136 make the list of columns and the list of values the same length.

INSERT INTO users (name, email) VALUES (?, ?);

3Verify

The statement runs in the mysql client first, then from PHP without an exception.

mysql -u app -p shop -e "SELECT email FROM users LIMIT 1"

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 4

The connection itself fails: wrong login, unknown database or no server

1Check

The exception is thrown by new mysqli(...) itself, before any query. 2002 means the local socket was not reachable. 2003 means the TCP connection to the host and port failed. Test the same values with the mysql client.

mysql -h 127.0.0.1 -P 3306 -u app -p -e "SELECT 1"

2Fix

Correct the user, password, database name, host and port in your config. For 2002 and 2003 first make sure the MySQL server is running and listens where the config says.

$mysqli = new mysqli('127.0.0.1', 'app', 'secret', 'shop', 3306);

3Verify

The mysql client and the PHP script connect with the same values.

php -r 'new mysqli("127.0.0.1", "app", "secret", "shop", 3306); echo "connected\n";'

Confirmed by dev.mysql.com

Did this fix it?

Cause 4 of 4

The table refuses the data you try to save

1Check

These codes mean the statement is valid but the value breaks a rule of the column: NULL in a NOT NULL column, text longer than the column, a value of the wrong type, or a key that already exists. Read the column definition.

SHOW COLUMNS FROM users;

2Fix

Validate and trim the input before the query, give the column a default or a bigger size where the design allows it, and handle 1062 by catching the exception and checking getCode() for 1062.

try {
    $stmt->execute();
} catch (mysqli_sql_exception $e) {
    if ($e->getCode() === 1062) {
        // the key exists already: show a message or update the row
    } else {
        throw $e;
    }
}

3Verify

A duplicate or an over-long value now produces your own message, not a fatal error.

# submit the same form twice and read the error log

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Set the report mode explicitly with mysqli_report at the start of the app, so it never depends on the PHP version.
  • Catch mysqli_sql_exception at one central place and log getCode() and getMessage(), never print them to visitors.
  • Keep schema changes in migrations that run on every environment, so a missing table or column cannot differ between them.
  • Use prepared statements, so a quote in the data cannot become a syntax error.

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.