.NET in Docker: 'Process terminated. Couldn't find a valid ICU package installed on the system'

Process terminated. Couldn't find a valid ICU package installed on the system. means the .NET runtime was told to use full globalization, but the image has no ICU libraries for it to load. On mcr.microsoft.com/dotnet/runtime:10.0-alpine, install icu-libs in the Dockerfile, or keep invariant mode on if the app needs no culture data.

The tested fix is two lines in the final stage: RUN apk add --no-cache icu-libs icu-data-full and ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false. After that the same app printed an Indian rupee amount with Indian digit grouping.

The error

PS> docker run --rm --name fix10-dn-icu -e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false fix10-dn-alpine culture
Process terminated.
Couldn't find a valid ICU package installed on the system. Please install libicu (or icu-libs) using your package manager and try again. Alternatively you can set the configuration flag System.Globalization.Invariant to true if you want to run with no globalization support. Please see https://aka.ms/dotnet-missing-libicu for more information.
   at System.Environment.FailFast(System.Runtime.CompilerServices.StackCrawlMarkHandle, System.String, System.Runtime.CompilerServices.ObjectHandleOnStack, System.String)
   at System.Environment.FailFast(System.Threading.StackCrawlMark ByRef, System.String, System.Exception, System.String)
   at System.Environment.FailFast(System.String)
   at System.Globalization.GlobalizationMode+Settings..cctor()
   at System.Globalization.CultureData.GetCultureData(System.String, Boolean)
   at System.Globalization.CultureInfo..ctor(System.String, Boolean)
   at Program.<Main>$(System.String[])

The container exited with code 139.

Why it happens

The runtime:10.0-alpine image sets DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true in its environment, and it ships without ICU. With that default, the app above did not hit this message at all; it threw a CultureNotFoundException instead. The message appeared once invariant mode was switched off (here with -e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false) while the image still had no ICU package.

The stack trace shows where it fails: the first new CultureInfo("en-IN") ends in GlobalizationMode+Settings..cctor(), which calls Environment.FailFast. That is why there is no catchable exception, just "Process terminated". The simple start-up message of the same app ran fine with the same setting; the crash came only when culture data was first needed.

The fix

FROM mcr.microsoft.com/dotnet/runtime:10.0-alpine
RUN apk add --no-cache icu-libs icu-data-full
ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet", "ClinicApi.dll"]

PS> docker run --rm --name fix10-dn-icu2 fix10-dn-alpine-icu culture
Fee for Maria Garcia: ₹12,34,567.89

The two Alpine packages put ICU into the image, and the ENV line overrides the image's invariant default, so the setting no longer depends on a run flag. If your app does not need cultures, the other way out is to leave invariant mode on (do not override the variable); then any culture-specific code meets the invariant-mode exception instead, which is its own post linked below.

How it was reproduced

A console app from dotnet new console -n ClinicApi with no packages, whose culture mode formats an amount with new CultureInfo("en-IN"), built in a multi-stage Dockerfile on mcr.microsoft.com/dotnet/sdk:10.0 (SDK 10.0.302) and run on mcr.microsoft.com/dotnet/runtime:10.0-alpine (Alpine 3.24.4, Microsoft.NETCore.App 10.0.15), Docker engine 29.9.3 on Windows 11. The error came from running that image with DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false.

Frequently asked

How do I install ICU in a .NET Alpine Docker image?

Add RUN apk add --no-cache icu-libs icu-data-full to the final stage of the Dockerfile and set ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false, because the mcr.microsoft.com/dotnet/runtime:10.0-alpine image sets it to true.

Why does my .NET app say Couldn't find a valid ICU package only in Docker?

The container image has no ICU libraries while globalization invariant mode is switched off. On the runtime:10.0-alpine image invariant mode is on by default, so something in your setup turned it off.

Can I catch the ICU package error in a try block?

No. In the test the runtime called Environment.FailFast and printed Process terminated, so the process ended without a catchable exception. Fix the image instead.

With invariant mode left on, the same code fails differently: Only the invariant culture is supported in globalization-invariant mode. More decoded errors in the Fixes category.