SQLSTATE[HY000] [2054] Server sent charset unknown to the client. Please, report to the developers

SQLSTATE[HY000] [2054] Server sent charset unknown to the client. Please, report to the developers

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Deciphering the "Server Sent Charset Unknown" Error in Laravel Migrations

When initializing a new login system or migrating an existing database, encountering SQLSTATE[HY000] [2054] Server sent charset unknown to the client immediately after updating your .env file is a common stumbling block. This error typically surfaces during the execution of php artisan migrate, preventing Laravel from even querying the information_schema.tables to check for pending migrations. The stack trace often points to Connection.php and Connector.php, ultimately failing within PDO with the message (255) unknown to the client.

This issue arises when there is a mismatch between the character set configuration expected by the MySQL or MariaDB server and what the client driver (PHP/PDO) is attempting to negotiate. Specifically, the error indicates that the server has sent a charset identifier of 255, which in the context of MySQL protocol usually signifies an undefined or unsupported character set for the current client version.

Investigating the Character Set Mismatch

The root cause is rarely a missing database configuration file; it is almost always a misalignment in how the connection parameters are defined versus what the server actually supports. When you run php artisan migrate, Laravel attempts to connect to your database instance (in this case, named kokodb). The PDO extension negotiates the character set upon establishing the TCP connection. If the server responds with an unknown charset code, the handshake fails before any SQL logic can execute.

To resolve this, you must inspect the MySQL configuration file, typically located at /etc/my.cnf or /etc/mysql/my.cnf, to see if a default character-set-server is set to a value that your PHP environment does not recognize or support natively. Common culprits include older or experimental character sets like cp932 (often associated with Japanese locales) or specific binary collations that might be configured as defaults but aren't standard in the client's context.

Corrective Steps for the Database Server

The most robust solution involves forcing the server to use a standard, universally supported character set, such as utf8mb4. You should edit your MySQL configuration file and ensure the following lines are present under the [mysqld] section:

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

After making these changes, you must restart the MySQL service for the settings to take effect:

sudo systemctl restart mysql
# or
sudo service mariadb restart

Once the server is restarted and configured to use a known charset, attempt running the migration again. The PDO driver should now successfully negotiate the connection parameters without triggering the unknown charset error.

Adjusting Laravel Connection Settings

If modifying the server configuration is not immediately feasible, you can sometimes mitigate the issue by explicitly defining the character set in your .env file. While this approach works for many standard cases, it may not resolve the specific (255) error caused by a malformed server default. However, it is worth verifying that your DB_CHARSET and DB_COLLATION keys are set to valid values:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=kokodb
DB_USERNAME=root
DB_PASSWORD=secret
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

It is important to note that simply adding these lines does not override a server-side default configuration that sends an invalid handshake token. The error originates from the protocol exchange layer, so the server-side fix remains the primary recommendation. If you are using a managed database service like AWS RDS or Google Cloud SQL, check the instance settings in the console to ensure the default character set has been updated, as these platforms sometimes retain legacy defaults upon creation.

Preventing Future Issues

When setting up new projects, always verify that your database engine version supports utf8mb4. While modern versions of MySQL and MariaDB support it out of the box, older instances might require explicit upgrades or configuration changes. Additionally, ensure that your PHP installation includes the necessary extensions for full Unicode support if you plan to store emojis or special characters in your login system fields.

By aligning the server's character set expectations with the client's capabilities, you eliminate this handshake failure and allow Laravel to proceed with creating the necessary migration tables for your application.

Our network