Postgres Container Locale/Encoding Init Failure in CI
The Postgres container failed during initdb because the requested locale, encoding, or collation is not available in the image. Initialization aborts, so the server never accepts connections and every later connect fails for a non-obvious reason.
What this error means
The Postgres service never becomes healthy; container logs show initdb complaining about an invalid or unavailable locale/encoding. Downstream steps then fail with connection refused because the server never started.
initdb: error: invalid locale settings; check LANG and LC_* environment variables
initdb: error: encoding "UTF8" does not match locale "en_US"Common causes
Locale not present in the image
Slim Postgres images may not include the requested locale (e.g. en_US.UTF-8), so initdb cannot configure it.
Encoding/collation mismatch
Requesting an encoding that does not match the chosen locale makes initdb refuse to initialize.
Bad timezone or LC_* values
Invalid TZ/LC_* values passed to the container break initialization before the server starts.
How to fix it
Use the C/UTF-8 locale for CI
The C locale is always available and avoids missing-locale failures.
services:
postgres:
image: postgres:16
env:
POSTGRES_PASSWORD: postgres
POSTGRES_INITDB_ARGS: "--locale=C --encoding=UTF8"Or pick an image that ships the locale
- Use a full image variant that includes
en_US.UTF-8, or generate the locale in a custom image. - Keep encoding consistent with the locale you request.
- Read the container logs to confirm initdb succeeded before debugging connections.
How to prevent it
- Default CI databases to the C locale unless you specifically need another.
- Match encoding to the locale you select.
- This is deterministic init configuration - retrying will not create a missing locale.