'Setting locale failed' on your server: what it means and fixes
Short answer: Warnings like "perl: warning: Setting locale failed", "cannot change locale (en_AU.UTF-8)" or "LC_ALL: cannot change locale" usually mean your session asked the server to use a locale the server hasn't generated. A common cause is SSH: Debian-based systems' default SSH client configuration sends your computer's LANG and LC_* settings to the server, which may not have that locale installed. Either generate the locale on the server, stop your SSH client sending it, or set a locale the server does have, such as C.UTF-8, for scripts and services. The warnings are mostly harmless, but they can hide real errors and occasionally break scripts that handle text.
What a locale is
The Linux locale(7) manual describes a locale as a set of language and cultural rules, covering messages, character sets, sorting conventions and formats such as dates and numbers. Programs choose their locale from environment variables. The manual explains the order: a non-empty LC_ALL is used first; otherwise each category variable such as LC_TIME or LC_CTYPE applies to its own category; otherwise LANG is used.
If those variables name a locale the system hasn't compiled, programs fall back to a default and many print warnings.
Why it happens after SSH login
Debian's ssh_config(5) manual notes that the system-wide client configuration includes SendEnv LANG LC_* among settings that differ from OpenSSH's defaults. SendEnv specifies which local environment variables are sent to the server; the server must also be configured to accept them, via AcceptEnv in its own configuration.
So if your laptop uses en_AU.UTF-8 and the server only has en_US.UTF-8 or C.UTF-8, every login sets a locale the server can't load. Typical symptoms:
- Perl warnings on login or when running package tools.
bash: warning: setlocale: LC_ALL: cannot change locale.- Python or other tools complaining about encodings.
- Odd characters in output, especially with non-English text.
Scheduled jobs and services may show different behaviour again, because they don't inherit your SSH session's variables.
Fix 1: Generate the locale on the server
Debian's locale-gen(8) manual explains that because compiled locales are large, only templates are shipped, and only the desired locales are compiled on the system. You select locales in /etc/locale.gen, then run locale-gen to compile them.
In practice:
- Uncomment the line for the locale you need, such as
en_AU.UTF-8 UTF-8, in/etc/locale.gen, or use your distribution's locale configuration tool. - Run
locale-gen. - Log out and back in.
This is the best fix when several people log in from different regions, or when you actually want that locale's formats on the server.
Fix 2: Stop sending your locale
If you'd rather the server use its own settings:
- Remove or override
SendEnv LANG LC_*in your SSH client configuration for that host, or - Remove
AcceptEnv LANG LC_*from the server's SSH configuration, so it ignores what clients send.
Changing the server's setting affects everyone who logs in, so agree it with your team.
Fix 3: Set a safe locale for scripts and services
For cron jobs, services and deployment scripts, set the locale explicitly rather than relying on whatever environment they inherit. C.UTF-8 is widely available on modern distributions and keeps UTF-8 text handling. Set LANG in the service definition, the script itself or the crontab, and avoid setting LC_ALL globally unless you have a reason, since it overrides everything.
Why it's worth fixing
- Noise hides problems. Warnings in every log and email make it easy to miss a real error.
- Text handling. Without a UTF-8 locale, some tools mishandle accented names, emoji or non-English text in filenames and data.
- Sorting and formats. Reports may sort or format numbers and dates differently between your laptop and the server.
Checking your settings
- Run
localeto see the current variables, andlocale -ato list locales the server has compiled. - Compare the two: any variable naming a locale not in the list will cause warnings.
- Check service and cron environments separately; they often differ from your login shell.
Bake it into new servers
The easiest time to get locales right is when a server is built. Add the locales your team and software need to your setup scripts or configuration management, set a system default, and document the choice. Do the same for container images: install the locale data you need, or set LANG=C.UTF-8 if the base image supports it, and confirm with locale -a during the build. Then a new server or container behaves the same as the old one, and nobody spends an afternoon chasing a warning that was solved years ago.
Databases care too
Some databases record a locale or collation when a database is created, and it affects sorting and text comparison. If you fix locales on a server that already hosts a database, check the database's own settings before assuming its behaviour has changed, and plan any collation change carefully, because it can affect indexes and the order of results.
An illustrative example
A hypothetical Geelong bookkeeping software company had developers in Australia and contractors in Europe logging into the same Debian server. Every login and package update printed locale warnings, and a nightly export occasionally mangled customer names with accents. The team generated en_AU.UTF-8 and en_GB.UTF-8 on the server, set LANG=C.UTF-8 explicitly in the export job's service definition, and the warnings and the mangled names both stopped.
FAQ
Are these warnings dangerous?
Usually not, but they can mask real errors and affect text handling.
Should I just set LC_ALL=C?
That silences warnings but loses UTF-8 handling. C.UTF-8 is generally better.
Why do containers show this too?
Minimal images often include few or no locales. Set LANG in the image.
Do I need to restart services?
Yes, services pick up locale changes when restarted.
If your servers fill logs with locale warnings or mangle non-English text, tell us what distribution you run.