diesel-rs/diesel · critical

Unable to perform MySQL global initialization

Error message

Unable to perform MySQL global initialization

What it means

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`.

Solutions

1. Fix the underlying client library: reinstall or match libmysqlclient/mariadb-connector-c version with the one diesel was built against.
2. Check and repair MySQL option/config files (~/.my.cnf, /etc/my.cnf) for malformed options referenced during library init.
3. Verify locale/charset environment variables (LANG, LC_ALL) are valid in the process environment (common in containers).
4. Restart the process once — since the failure may be transient environment corruption, a fresh process can re-attempt global init.

Example fix

// before (Dockerfile)
FROM debian:bookworm
RUN apt-get install -y libmariadb-dev  # mismatched client at runtime

// after
FROM debian:bookworm
RUN apt-get install -y libmariadb-dev && rm -f ~/.my.cnf  # valid client + clean config

// before creating connections, sanity-check client lib availability
// e.g. ensure libmysqlclient is loadable and ~/.my.cnf parses (mysql --help > /dev/null)

// Rust: catch_unwind around the first establish since diesel panics
let conn = std::panic::catch_unwind(|| MysqlConnection::establish(url));
match conn { Ok(Ok(c)) => c, _ => /* fallback / report init failure */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• not implemented
• Maximal supported day interval size is 32 bit
• DIESEL_MAX_COLUMN_COUNT is a number that fits into a u16
• Using window functions in WHERE clauses is not supported
• Error closing SQLite connection

AI-assisted analysis of diesel-rs/diesel@6fa6ed01b2 (2026-09-07). Data as JSON: /api/errors/f9c970731b2b9a6b. Report an issue: GitHub.

Appendix: source

Thrown at diesel/src/mysql_like/connection/raw.rs:308

/// > to protect the `mysql_library_init()` call. This should be done prior to
/// > any other client library call.
///
/// <https://dev.mysql.com/doc/c-api/8.4/en/mysql-init.html>
static MYSQL_THREAD_UNSAFE_INIT: Once = Once::new();

fn perform_thread_unsafe_library_initialization() {
    MYSQL_THREAD_UNSAFE_INIT.call_once(|| {
        // mysql_library_init is defined by `#define mysql_library_init mysql_server_init`
        // which isn't picked up by bindgen
        let error_code = unsafe { ffi::mysql_server_init(0, ptr::null_mut(), ptr::null_mut()) };
        if error_code != 0 {
            // FIXME: This is documented as Nonzero if an error occurred.
            // Presumably the value has some sort of meaning that we should
            // reflect in this message. We are going to panic instead of return
            // an error here, since the documentation does not indicate whether
            // it is safe to call this function twice if the first call failed,
            // so I will assume it is not.
            panic!("Unable to perform MySQL global initialization");
        }
    })
}

View on GitHub (pinned to 6fa6ed01b2)