How to fix BadValue: invalid parameter in MongoDB

MongoDBBEGINNERHIGHUpdated Dec 22, 2025· 111 views

MongoDB throws "BadValue: invalid parameter" during global initialization when it cannot parse the requested locale (LANG / LC_*). Setting a generated UTF-8 locale before mongod/mongos starts and ensuring services inherit those values keeps the server from failing with error code 2.

Quick fix

Fixes BadValue: invalid parameter

export LANG="en_US.UTF-8"
            export LC_ALL="en_US.UTF-8"
            env | grep -E "^(LANG|LC_)"
            mongod --config /etc/mongod.conf
  1. Export a UTF-8 locale before launching MongoDB
  2. Generate the locale that MongoDB expects
  3. Pass the locale into systemd units and containers
mongodb — error
export LANG="en_US.UTF-8"
            export LC_ALL="en_US.UTF-8"
            env | grep -E "^(LANG|LC_)"
            mongod --config /etc/mongod.conf
BadValue: invalid parameter

What this error means

The "BadValue: invalid parameter" error surfaces before MongoDB finishes global initialization. The server reads glibc locale settings (LANG and LC_* environment variables) and fails immediately once it sees that the requested locale is empty, missing, or not installed, which is reported as an invalid parameter (BadValue 2). Stack Overflow question 27375137 shows the same failure when LANG/LC_ALL are unset, and the MongoDB error-code reference confirms that BadValue is the catch-all thrown whenever MongoDB receives a disallowed startup parameter such as an invalid locale string.

Typical symptoms

  • mongod fails to start with "Failed global initialization: BadValue Invalid or no user locale set. Please ensure LANG and/or LC_* environment variables are set correctly. Missing: [parameter]"
  • mongo shell, mongos, or `mongosh --eval "db.runCommand({ping: 1})"` returns `BadValue: invalid parameter` before a connection is established
  • systemctl status mongod shows the process crashed with "BadValue invalid parameter" and the journal points to locale initialization
  • Running `env | grep -E "^(LANG|LC_)"` inside the environment that launches MongoDB shows no matching variables or only `LANG=C`
  • Reproducible failure in lightweight containers or CI images that do not generate any locales

Common causes

  1. LANG/LC_* environment variables are not exported in the shell owner or are stripped away by the service manager, leaving MongoDB with an empty locale string
  2. The value points to a locale (e.g., `en_US.UTF-8`) that was never generated on the host, so glibc rejects it as invalid
  3. Minimal containers/docker images and systemd units often clear locale variables unless you explicitly pass them, so MongoDB starts with an invalid parameter
  4. A locale package is missing (no `/usr/lib/locale/en_US.utf8/` data), which makes any LANG value appear invalid
  5. Misconfigured mongod.conf, invalid option names, or wrong data-directory permissions can also trigger BadValue during startup, so double-check the config if locale fixes do not help

How to fix "BadValue: invalid parameter"

1Export a UTF-8 locale before launching MongoDB

Set LANG and LC_ALL in the shell right before starting mongod, mongos, or the mongo shell so the daemon never sees a blank locale parameter:

bash
export LANG="en_US.UTF-8"
            export LC_ALL="en_US.UTF-8"
            env | grep -E "^(LANG|LC_)"
            mongod --config /etc/mongod.conf

Persist the exports by appending them to ~/.bashrc, ~/.profile, or your CI manifest so every invocation of the binary inherits the locale. Replace en_US.UTF-8 with another available locale if you are targeting a different language.

2Generate the locale that MongoDB expects

Missing locale definitions make any LANG value appear invalid. On Debian/Ubuntu:

bash
sudo apt-get install -y locales
            sudo locale-gen en_US.UTF-8
            sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8
            locale -a | grep -i en_US

On RHEL/CentOS:

bash
sudo yum install -y glibc-langpack-en
            sudo localedef -i en_US -f UTF-8 en_US.UTF-8
            localectl list-locales | grep -i en_US

After generating the locale, restart the shell or service so the new definitions become available to MongoDB at startup.

3Pass the locale into systemd units and containers

systemd and container runtimes start mongod with a sanitized environment, so even if you export LANG in your login shell, the service may still see an empty parameter. Create a systemd drop-in to keep the locale available:

bash
sudo mkdir -p /etc/systemd/system/mongod.service.d
            cat <<'EOF' | sudo tee /etc/systemd/system/mongod.service.d/locale.conf
            [Service]
            Environment="LANG=en_US.UTF-8"
            Environment="LC_ALL=en_US.UTF-8"
            EOF
            sudo systemctl daemon-reload
            sudo systemctl restart mongod
            systemctl show mongod -p Environment

For Docker Compose or docker run, pass the same variables explicitly:

yaml
environment:
              LANG: en_US.UTF-8
              LC_ALL: en_US.UTF-8

This ensures every container or service process starts with the valid locale parameter that MongoDB expects.

Advanced notes

Refer to Stack Overflow question 27375137 and the Medium write-up about MongoDB on CentOS for the same startup failure and resolution. Use localectl list-locales or locale -a to confirm the desired locale is installed, and run mongod --config /etc/mongod.conf --configCheck if BadValue persists—invalid entries in mongod.conf or incorrect file permissions can also surface as BadValue. For non-systemd runtimes, make sure your shell/environment scripts source the exports before launching mongod so the parameter is never empty.

Frequently asked questions

What does "BadValue: invalid parameter" mean?
The "BadValue: invalid parameter" error surfaces before MongoDB finishes global initialization. The server reads glibc locale settings (LANG and LC_* environment variables) and fails immediately once it sees that the requested locale is empty, missing, or not installed, which is reported as an invalid parameter (BadValue 2). Stack Overflow question 27375137 shows the same failure when LANG/LC_ALL are unset, and the MongoDB error-code reference confirms that BadValue is the catch-all thrown whenever MongoDB receives a disallowed startup parameter such as an invalid locale string.
How do I fix "BadValue: invalid parameter"?
MongoDB throws "BadValue: invalid parameter" during global initialization when it cannot parse the requested locale (LANG / LC_*). Setting a generated UTF-8 locale before mongod/mongos starts and ensuring services inherit those values keeps the server from failing with error code 2.
What causes "BadValue: invalid parameter"?
LANG/LC_* environment variables are not exported in the shell owner or are stripped away by the service manager, leaving MongoDB with an empty locale string The value points to a locale (e.g., en_US.UTF-8) that was never generated on the host, so glibc rejects it as invalid Minimal containers/docker images and systemd units often clear locale variables unless you explicitly pass them, so MongoDB starts with an invalid parameter
Is the "BadValue: invalid parameter" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading