symfony/polyfill-mbstring · error · ValueError

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

Error message

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

What it means

Mbstring::mb_internal_encoding() throws this ValueError when the requested encoding name is not supported. This polyfill only supports 'UTF-8', and on PHP >= 8.0 an invalid encoding raises a ValueError instead of returning false (which is the pre-8.0 behavior). It is rethrown via mb_internal_encoding and its internal callers (mb_str_split, mb_scrub, mb_str_pad, mb_ucfirst, mb_lcfirst, mb_internal_trim).

Solutions

1. Use 'UTF-8' as the encoding — this polyfill only supports UTF-8
2. Convert your data to UTF-8 (e.g. iconv/mb_convert_encoding via ext-mbstring or a converter) instead of asking for another encoding
3. Install the native ext-mbstring extension if non-UTF-8 encodings are required
4. Wrap the call in try/catch (ValueError on PHP 8+, or check the false return value on PHP < 8)

Example fix

// before
mb_internal_encoding('ISO-8859-1');
// after
mb_internal_encoding('UTF-8'); // polyfill supports UTF-8 only

if ($encoding !== null && !@mb_check_encoding('', $encoding)) {
    $encoding = 'UTF-8';
}
mb_internal_encoding($encoding);

function isValidEncoding(?string $encoding): bool
{
    return $encoding === null || @mb_check_encoding('', $encoding);
}

try {
    mb_internal_encoding($encoding);
} catch (\ValueError $e) {
    mb_internal_encoding('UTF-8'); // polyfill default
}

When it happens

Trigger: Calling mb_internal_encoding('ISO-8859-1') (or any encoding other than 'UTF-8') with $encoding != null when PHP_VERSION_ID >= 80000; indirectly, calling mb_scrub/mb_str_pad/mb_ucfirst/mb_lcfirst/mb_internal_trim with an explicit unsupported $encoding argument.

Common situations: Porting legacy code that used ISO-8859-1/Windows-1252 encodings with ext-mbstring to this polyfill; misremembering that the polyfill supports all mbstring encodings when it only supports UTF-8; passing a user-supplied charset from config or HTTP headers without whitelisting UTF-8.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• (dynamic: errorFormat passed to assertEncoding, e.g…
• (dynamic: errorFormat passed to assertEncoding, e.g…
• Argument #1 ($language) must be a valid language
• Argument #2 ($length) must be greater than 0
• Argument #1 ($substitute_character) must be "none", "long"…

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

Appendix: source

Thrown at Mbstring.php:415

    public static function mb_internal_encoding($encoding = null)
    {
        if (null === $encoding) {
            return self::$internalEncoding;
        }

        $normalizedEncoding = self::getEncoding($encoding);

        if ('UTF-8' === $normalizedEncoding || false !== @iconv($normalizedEncoding, $normalizedEncoding, ' ')) {
            self::$internalEncoding = $normalizedEncoding;

            return true;
        }

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

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

    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;

View on GitHub (pinned to d3d318bad5)