Error 2021 indicates a failed attempt to use MySQL’s embedded server protocol instead of a normal client connection.
MySQL Error 2021: CR_EMBEDDED_CONNECTION happens when a client library or tool mistakenly tries to start an embedded MySQL server rather than open a standard network connection. Use the non-embedded client library or set the protocol to TCP/UNIX socket to resolve.
Embedded server
Error 2021 appears when a program linked against the embedded version of libmysqlclient calls mysql_real_connect without an initialized embedded server context. The client library returns CR_EMBEDDED_CONNECTION with the message “Embedded server.”
The condition signals that the request cannot be routed through an in-process MySQL server, so the connection fails before any SQL reaches the server.
Fixing it quickly restores connectivity and prevents application downtime.
Developers usually meet the error after switching build flags from -lmysqlclient to -lmysqld or when using mysql --protocol=PIPE on platforms that treat PIPE as an embedded call.
GUI tools compiled with embedded support can also trigger it if the embedded engine is disabled at runtime.
The problem can surface on MySQL 5.7, 8.0 and MariaDB forks because the client library checks the protocol field early and aborts if embedded mode is unsupported.
Connection failures halt application workflows, scheduled jobs and CI pipelines. Misclassified errors can waste debugging time.
Correcting library linkage or connection flags removes the blocker and prevents repeat outages.
A mismatched client library that expects an embedded server but is linked into an application that should connect over TCP is the primary trigger.
Build scripts that add -DWITH_EMBEDDED_SERVER without enabling mysqld initialization also cause it.
Using mysql_options with MYSQL_OPT_USE_EMBEDDED_CONNECTION=1, or running the mysql CLI with --protocol=PIPE or --protocol=MEMORY on systems where those map to the embedded handler, is another common cause.
First verify which libmysqlclient your binary loads. Use ldd or otool to confirm.
Relink against the standard client library if the embedded variant appears.
If your tool must remain embedded-capable, call mysql_library_init and mysql_server_init before mysql_real_connect, or set MYSQL_OPT_USE_EMBEDDED_CONNECTION to 0 with mysql_options.
Build pipelines that automatically pick libmysqld during static builds frequently break at runtime. Explicitly add -lmysqlclient to override the default.
On Windows, MINGW builds of the mysql CLI with ENABLE_EMBEDDED limit protocols.
Launch mysql --protocol=TCP or remove the option from ~/.my.cnf to connect normally.
Pin the correct client library in your build tooling and CI containers. Keep separate Docker images for embedded and network clients.
Set explicit connection protocols in configuration files. Monitor startup logs for “Trying to use embedded connection” and alert early.
Error 2020 CR_EMBEDDED_CONNECTION_FAILURE occurs when the embedded server starts but later crashes.
The fixes overlap: review linkage and runtime flags.
Error 2002 CR_CONNECTION_ERROR reports generic network failures and is resolved by checking host, port and socket permissions.
.
No. It usually means your client library tried embedded mode. The external MySQL server may still be running.
It affects MySQL 5.1 through 8.0 and MariaDB when the embedded client library is involved.
Retrying without changing the protocol will fail again. Fix the linkage or connection settings first.
Galaxy packages the non-embedded libmysqlclient and forces TCP or UNIX socket protocols, so embedded misconfigurations cannot surface.
.avif)
.avif){kind=logo}
