{"record":{"id":"f9c970731b2b9a6b","repo":"diesel-rs/diesel","slug":"unable-to-perform-mysql-global-initialization","errorCode":null,"errorMessage":"Unable to perform MySQL global initialization","messagePattern":"Unable to perform MySQL global initialization","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"diesel/src/mysql_like/connection/raw.rs","lineNumber":308,"sourceCode":"/// > to protect the `mysql_library_init()` call. This should be done prior to\n/// > any other client library call.\n///\n/// <https://dev.mysql.com/doc/c-api/8.4/en/mysql-init.html>\nstatic MYSQL_THREAD_UNSAFE_INIT: Once = Once::new();\n\nfn perform_thread_unsafe_library_initialization() {\n    MYSQL_THREAD_UNSAFE_INIT.call_once(|| {\n        // mysql_library_init is defined by `#define mysql_library_init mysql_server_init`\n        // which isn't picked up by bindgen\n        let error_code = unsafe { ffi::mysql_server_init(0, ptr::null_mut(), ptr::null_mut()) };\n        if error_code != 0 {\n            // FIXME: This is documented as Nonzero if an error occurred.\n            // Presumably the value has some sort of meaning that we should\n            // reflect in this message. We are going to panic instead of return\n            // an error here, since the documentation does not indicate whether\n            // it is safe to call this function twice if the first call failed,\n            // so I will assume it is not.\n            panic!(\"Unable to perform MySQL global initialization\");\n        }\n    })\n}\n","sourceCodeStart":290,"sourceCodeEnd":312,"githubUrl":"https://github.com/diesel-rs/diesel/blob/6fa6ed01b24b24248ab2a611698d0a7c6a2e9120/diesel/src/mysql_like/connection/raw.rs#L290-L312","documentation":"MySQL client libraries (mysqlclient) require a one-time global library initialization (mysql_library_init) before any connection can be made. Diesel performs this initialization thread-unsafely when a MySQL-like connection is created; if the underlying C call returns a nonzero (error) result, diesel panics because the client docs don't guarantee re-calling after failure. This panic aborts connection establishment inside `MysqlConnection::establish`/`new`.","triggerScenarios":"Calling diesel::mysql::MysqlConnection::establish (or via Pool::get) when mysql_library_init returns an error — typically due to a broken/mismatched libmysqlclient installation, malformed MySQL config files (~/.my.cnf, my.ini), or corrupted charset/locale settings the library reads during init.","commonSituations":"Docker/system environments with a different libmysqlclient than the one diesel was compiled against; invalid or unreadable my.cnf files with bad option groups; running with unusable locale environment variables (e.g. broken LC_ALL) that the C library fails on at init.","solutions":["Fix the underlying client library: reinstall or match libmysqlclient/mariadb-connector-c version with the one diesel was built against.","Check and repair MySQL option/config files (~/.my.cnf, /etc/my.cnf) for malformed options referenced during library init.","Verify locale/charset environment variables (LANG, LC_ALL) are valid in the process environment (common in containers).","Restart the process once — since the failure may be transient environment corruption, a fresh process can re-attempt global init."],"exampleFix":"// before (Dockerfile)\nFROM debian:bookworm\nRUN apt-get install -y libmariadb-dev  # mismatched client at runtime\n\n// after\nFROM debian:bookworm\nRUN apt-get install -y libmariadb-dev && rm -f ~/.my.cnf  # valid client + clean config","handlingStrategy":"try-catch","validationCode":"// before creating connections, sanity-check client lib availability\n// e.g. ensure libmysqlclient is loadable and ~/.my.cnf parses (mysql --help > /dev/null)","typeGuard":null,"tryCatchPattern":"// Rust: catch_unwind around the first establish since diesel panics\nlet conn = std::panic::catch_unwind(|| MysqlConnection::establish(url));\nmatch conn { Ok(Ok(c)) => c, _ => /* fallback / report init failure */ }","preventionTips":["Pin libmysqlclient/mariadb-connector-c versions between build and runtime images.","Keep MySQL option files (~/.my.cnf, /etc/my.cnf) valid and readable in all environments.","Verify LANG/LC_ALL env vars are valid in containers.","Initialize connections once at startup (pooled) so init failures surface immediately, not mid-request."],"tags":["mysql","initialization","panic","diesel"],"backgroundTag":"module-init-failed","analyzedSha":"6fa6ed01b24b24248ab2a611698d0a7c6a2e9120","analyzedAt":"2026-09-07T01:50:13.074Z","contentChangedAt":"2026-09-07T01:50:13.074Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}