python/cpython · warning

Error setting LC_CTYPE, skipping C locale coercion\n

Error message

Error setting LC_CTYPE, skipping C locale coercion\n

What it means

Emitted during C locale coercion in CPython startup (Python/pylifecycle.c, _coerce_default_locale_settings) when setenv("LC_CTYPE", target_locale, 1) fails. The interpreter was trying to upgrade a legacy C locale to a UTF-8 capable one and could not export the LC_CTYPE variable, so it skips coercion entirely (returns 0) and continues with the original locale. This is a best-effort path: startup proceeds, only the coercion is abandoned.

Source

Thrown at Python/pylifecycle.c:288

}


#ifdef PY_COERCE_C_LOCALE
static const char C_LOCALE_COERCION_WARNING[] =
    "Python detected LC_CTYPE=C: LC_CTYPE coerced to %.20s (set another locale "
    "or PYTHONCOERCECLOCALE=0 to disable this locale coercion behavior).\n";

static int
_coerce_default_locale_settings(int warn, const _LocaleCoercionTarget *target)
{
    const char *newloc = target->locale_name;

    /* Reset locale back to currently configured defaults */
    _Py_SetLocaleFromEnv(LC_ALL);

    /* Set the relevant locale environment variable */
    if (setenv("LC_CTYPE", newloc, 1)) {
        fprintf(stderr,
                "Error setting LC_CTYPE, skipping C locale coercion\n");
        return 0;
    }
    if (warn) {
        fprintf(stderr, C_LOCALE_COERCION_WARNING, newloc);
    }

    /* Reconfigure with the overridden environment variables */
    _Py_SetLocaleFromEnv(LC_ALL);
    return 1;
}
#endif

int
_Py_CoerceLegacyLocale(int warn)
{
    int coerced = 0;
#ifdef PY_COERCE_C_LOCALE

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Set a proper locale explicitly so coercion is never attempted: LANG=C.UTF-8 (or LC_CTYPE) in the container/service environment
2. If coercion is unwanted, disable it with PYTHONCOERCECLOCALE=0
3. In embedded scenarios, ensure environ is valid before Py_Initialize and that setenv is permitted

Example fix

# before (docker)
ENV LC_ALL=
# after (docker)
ENV LANG=C.UTF-8

# container: set a real locale so coercion is never attempted
ENV LANG=C.UTF-8

When it happens

Trigger: setenv failing: the process environment is immutable or malformed (environ replaced, insufficient memory for a new entry, restricted sandboxes that block putenv/setenv). Occurs only when PY_COERCE_C_LOCALE is compiled in, the runtime locale is C/POSIX, and a coercion target (e.g. C.UTF-8) exists.

Common situations: Minimal containers with tiny environments; embedded interpreters where the host application replaced `environ`; seccomp/sandbox profiles blocking setenv; exotic platforms with non-POSIX environment handling.

Related errors

• Python detected LC_CTYPE=C: LC_CTYPE coerced to %.20s (set a
• Warning: failed setting the LC_CTYPE environment variable to
• %s
• timezone changed during initialization
• posix_spawnattr_setbinpref failed to copy\n

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/eb18f1cc6253498c. Report an issue: GitHub.