symfony/polyfill-mbstring · error · ValueError

Argument #1 ($language) must be a valid language

Error message

Argument #1 ($language) must be a valid language, "%s" given

What it means

Mbstring::mb_language() throws this ValueError when the requested language name is not recognized. Only a fixed set of languages is accepted, and on PHP >= 8.0 an invalid name throws instead of returning false (pre-8.0 behavior).

Solutions

1. Pass one of the supported language names exactly (e.g. 'uni', 'Japanese', 'English' — check the polyfill's accepted list)
2. Guard the value against the supported list before calling
3. Omit the argument or pass null to just read the current language
4. On PHP < 8 rely on the false return value; on PHP >= 8 catch \ValueError

Example fix

// before
mb_language('en');
// after
mb_language('English'); // use an exact supported language name

$supported = ['uni','none','Japanese','ja','English','en','UTF-8','ASCII','EUC-JP','SJIS'];
if (!in_array($lang, $supported, true)) {
    $lang = 'uni';
}
mb_language($lang);

function isSupportedLanguage(?string $lang): bool
{
    return $lang === null || @mb_language($lang) !== false;
}

try {
    mb_language($lang);
} catch (\ValueError $e) {
    mb_language('uni');
}

When it happens

Trigger: Calling mb_language('...') with a $lang that is not null and not one of the supported language names (e.g. a typo like 'en' or 'english' instead of 'English').

Common situations: Passing lowercase or free-form language names from config; assuming any BCP-47 tag like 'en-US' is valid; copying code written for a different mbstring version with a different language list.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Argument #1 ($encoding) must be a valid encoding
• Argument #2 ($length) must be greater than 0
• Argument #1 ($substitute_character) must be "none", "long"…
• mb_str_pad(): Argument #3 ($pad_string) must be a non-empty…
• mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT…

AI-assisted analysis of symfony/polyfill-mbstring@d3d318bad5 (2026-09-13). Data as JSON: /api/errors/aa56378997a45dfd. Report an issue: GitHub.

Appendix: source

Thrown at Mbstring.php:436

    public static function mb_language($lang = null)
    {
        if (null === $lang) {
            return self::$language;
        }

        switch ($normalizedLang = strtolower($lang)) {
            case 'uni':
            case 'neutral':
                self::$language = $normalizedLang;

                return true;
        }

        if (80000 > \PHP_VERSION_ID) {
            return false;
        }

        throw new \ValueError(\sprintf('Argument #1 ($language) must be a valid language, "%s" given', $lang));
    }

    public static function mb_list_encodings()
    {
        return ['UTF-8'];
    }

    public static function mb_encoding_aliases($encoding)
    {
        switch (strtoupper($encoding)) {
            case 'UTF8':
            case 'UTF-8':
                return ['utf8'];
        }

        return false;
    }

View on GitHub (pinned to d3d318bad5)