Decoding PDO Error: Server Sent Charset (255) Unknown to the Client
When debugging a connection error in a Symfony 3 application running inside Docker, you might encounter a confusing message from the PDO driver: PDO::__construct(): Server sent charset (255) unknown to the client. Please, report to the developers. At first glance, it looks like a bug in PHP or the database server. However, this is almost always a protocol negotiation failure caused by how the MySQL client library handles character set metadata versus what the application explicitly requests.
In your specific scenario, you are connecting from PHP 7.1.3 using the pdo_mysql driver to a MySQL 8.0.1 instance. You have configured the DSN with charset=UTF8, yet the server responds with an unknown charset ID of 255. This mismatch prevents the PDO constructor from initializing the connection, resulting in the script terminating before any schema creation or data retrieval can occur.
The Protocol Negotiation Mismatch
To understand why this happens, you need to look at how the MySQL protocol handles character sets during the handshake phase. When a client connects to MySQL, it sends an initial packet indicating the character set it supports and its preferred default. The server responds with its own character set ID.
In modern MySQL (version 5.6+), the server uses specific integer IDs for character sets. For example, 33 is typically utf8mb4, which is the recommended encoding for new applications because it supports emojis and other extended Unicode characters. However, older documentation or legacy configurations often refer to UTF-8 simply as ID 33 or sometimes default to an ambiguous value if not explicitly configured.
The error message indicates that the server sent a character set ID of 255. In MySQL internals, 255 is a special reserved value used to indicate "default" or "unknown" when the specific charset name cannot be mapped cleanly to a numeric ID during the handshake, or when the client and server versions disagree on how to interpret the requested encoding.
When you specify charset=UTF8 in your DSN string "mysql:host=mysql;dbname=database;charset=UTF8;", PHP's PDO driver attempts to negotiate this specific character set with the MySQL 8.0.1 server. If the server does not have a direct mapping for the string literal "UTF8" (which technically should map to utf8mb4 in modern versions) or if the connection options are not parsed correctly by the underlying libmysqlclient, the server may respond with the fallback ID of 255. The PDO driver then throws an exception because it does not recognize ID 255 as a valid charset for initializing the session.
Fixing the Connection String
The most direct way to resolve this is to align your DSN with the actual character set IDs supported by MySQL 8.0.1. The pdo_mysql extension maps standard names like utf8 and utf8mb4 to numeric IDs, but explicit mismatches can trigger the "unknown" flag.
Instead of relying on the generic UTF8 string in your DSN, try explicitly requesting utf8mb4. This is the standard for modern MySQL deployments and ensures that the server recognizes the request as a valid 4-byte UTF-8 mapping rather than falling back to the legacy or ambiguous ID.
Update your .env file or configuration array accordingly:
'dsn' => 'mysql:host=mysql;dbname=database;charset=utf8mb4',
'options' => [
PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8mb4",
]
By setting the PDO::MYSQL_ATTR_INIT_COMMAND option, you force the connection to execute a query immediately after handshake that explicitly sets the connection's character set to utf8mb4. This bypasses the handshake ambiguity by ensuring that regardless of what the server sends initially, the session is forced into a known state before any application logic runs.
Verifying Docker Environment Variables
Since you are running both PHP and MySQL in Docker containers, environment variables can sometimes override configuration files or DSN strings if not handled carefully. Ensure that your docker-compose.yml or container entrypoint scripts are not injecting conflicting charset settings into the MySQL server itself.
Check the MySQL container's my.cnf or equivalent configuration to ensure that the default character set for new connections is defined explicitly. A common configuration block in /etc/mysql/mysql.conf.d/mysqld.cnf should look like this:
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init-connect='SET NAMES "utf8mb4"'
If the server defaults to latin1 or an unconfigured state, and your client requests UTF8, the negotiation fails. The configuration above ensures that even if the handshake is ambiguous, the server initializes with the correct encoding immediately.
Why This Matters for Schema Creation
You mentioned trying to create a MySQL schema via a Symfony console command. If the connection fails at the PDO level during initialization, no SQL commands execute. Even if you fix the connection, your schema definitions must match the character set of the tables being created.
If you connect with utf8mb4 but your table columns are defined as VARCHAR(255) CHARACTER SET utf8, MySQL will warn about truncation or implicit casting, which can lead to data loss. Always ensure that your migration files or schema definitions specify utf8mb4 for string columns if you intend to store international text or special characters. This consistency prevents runtime errors later in the application lifecycle.
By aligning the DSN, the connection attributes, and the server configuration to utf8mb4, you eliminate the "unknown charset" error and ensure a stable foundation for your Symfony application's database layer.
