Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A .NET app throws culture errors inside a Docker container

ErrorOnly the invariant culture is supported in globalization-invariant mode.

Short answer

Some container images, including Alpine runtime images, ship without ICU, so .NET starts in globalization-invariant mode. In that mode creating any culture except the invariant one throws CultureNotFoundException. Either install ICU and turn invariant mode off, or allow cultures to be created and accept invariant data.

  • Applies to .NET 8, .NET 9, Alpine-based dotnet images
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out whether the container runs in invariant mode. If this prints 1 or true, the image has no ICU or the setting was switched on.

    docker run --rm --entrypoint printenv my-image DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
  2. 2Match what you see, then jump to its fix

    1. 1The error appears only in the container, not on your machine, and the image is an Alpine aspnet, runtime or runtime-deps image.The base image has no ICU, so invariant mode is onFix
    2. 2The error persists after ICU is installed.Invariant mode is switched on in the project or environmentFix
    3. 3CultureNotFoundException from new CultureInfo("en-US") or CultureInfo.GetCultureInfo(...).You want to stay in invariant mode but the code creates named culturesFix

What does the error look like?

  • Only the invariant culture is supported in globalization-invariant mode.
  • en-us is an invalid culture identifier.
  • System.Globalization.CultureNotFoundException

Cause 1 of 3

The base image has no ICU, so invariant mode is on

1Check

The .NET Docker project lists Alpine aspnet, monitor, runtime and runtime-deps images, Azure Linux distroless images and Ubuntu chiseled images as images without ICU that enable invariant mode.

grep -n "^FROM" Dockerfile

2Fix

In the final stage of an Alpine image, install ICU and switch invariant mode off. Use a Debian or Ubuntu based image if you would rather not manage this.

ENV \
    DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false \
    LC_ALL=en_US.UTF-8 \
    LANG=en_US.UTF-8

RUN apk add --no-cache \
    icu-data-full \
    icu-libs

3Verify

Rebuild, run the container and repeat the request that threw the error.

docker build -t my-image . && docker run --rm -p 8080:8080 my-image

Confirmed by github.com

Did this fix it?

Cause 2 of 3

Invariant mode is switched on in the project or environment

1Check

Invariant mode can be set in the project file (InvariantGlobalization), in runtimeconfig.json (System.Globalization.Invariant) or with the environment variable. The project file or runtimeconfig.json value takes priority over the environment variable.

grep -rn "InvariantGlobalization" --include=*.csproj --include=*.props .
grep -n "Invariant" bin/Release/*/*.runtimeconfig.json

2Fix

Set the property to false (or remove it), then rebuild.

<PropertyGroup>
  <InvariantGlobalization>false</InvariantGlobalization>
</PropertyGroup>

3Verify

Rebuild and check the generated runtimeconfig.json no longer says true.

dotnet build -c Release && grep -n Invariant bin/Release/*/*.runtimeconfig.json

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

You want to stay in invariant mode but the code creates named cultures

1Check

Since .NET 6, invariant mode throws when code creates any culture other than the invariant one. Before .NET 6 it silently returned invariant data.

grep -rn "new CultureInfo\|GetCultureInfo\|CreateSpecificCulture" --include=*.cs .

2Fix

Set PredefinedCulturesOnly to false. Cultures can then be created, but they behave like the invariant culture, so formats and sorting will not be locale specific. Install ICU if you need real culture data.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

3Verify

Rebuild and run the code path that created the culture.

dotnet run -c Release

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Decide on purpose whether the service needs real culture data, and write that choice into the Dockerfile.
  • Pass culture names through your own code path so a missing culture is one clear error.
  • Run the container image, not only dotnet run, in CI.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.