twigphp/Twig · critical · RuntimeError

Unable to convert encoding: required function iconv() does…

Error message

Unable to convert encoding: required function iconv() does not exist. You should install ext-iconv or symfony/polyfill-iconv.

What it means

CoreExtension::convertEncoding relies on PHP's iconv() function to convert string encodings for filters like `random`, `reverse`, and `shuffle`. If the iconv extension (or its polyfill) is not loaded, the function cannot work and throws this RuntimeError up front instead of failing with an undefined-function fatal error.

Solutions

Install/enable ext-iconv: add `extension=iconv` to php.ini (check `php -m | grep iconv`)
Or require the polyfill: `composer require symfony/polyfill-iconv`
Rebuild the PHP Docker image including libiconv / the iconv extension
Verify in the same SAPI that renders templates (`php -r "var_dump(function_exists('iconv'));"`), since CLI and FPM configs can differ

Example fix

// before: composer.json without iconv support
{}
// after
composer require symfony/polyfill-iconv
// and/or php.ini
extension=iconv

Defensive patterns

Strategy: fallback

Validate before calling

if (!\function_exists('iconv')) {
    throw new \RuntimeException('ext-iconv or symfony/polyfill-iconv is required');
}

Try / catch

try {
    return $twig->render($template, $vars);
} catch (\Twig\Error\RuntimeError $e) {
    if (str_contains($e->getMessage(), 'iconv()')) {
        // degrade: avoid reverse/shuffle filters or use mb_* based custom filters
    } else { throw $e; }
}

Prevention

Add ext-iconv to production and CI PHP images
composer require symfony/polyfill-iconv as a safety net
Assert function_exists('iconv') in a boot/health check
Verify extension availability in the same SAPI (CLI vs FPM) used for rendering

When it happens

Trigger: Rendering a Twig template that calls the `reverse`, `shuffle`, or `random` filter on a multibyte string, or calling CoreExtension::convertEncoding directly, on a PHP installation where function_exists('iconv') is false — i.e. ext-iconv not compiled/loaded and symfony/polyfill-iconv not installed.

Common situations: Docker/PHP images built with --disable-iconv or without the iconv extension; minimal shared-hosting PHP builds; missing `extension=iconv` in php.ini (CLI vs web-server SAPI differences); composer install skipped polyfills.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of twigphp/Twig@a414c3a491 (2026-09-13). Data as JSON: /api/errors/9be2b02e5ed75e65. Report an issue: GitHub.

Appendix: source

Thrown at src/Extension/CoreExtension.php:1271

     *
     * @internal
     */
    public static function spaceless($content): string
    {
        return trim(preg_replace('/>\s+</', '><', $content ?? ''));
    }

    /**
     * @param string|null $string
     * @param string      $to
     * @param string      $from
     *
     * @internal
     */
    public static function convertEncoding($string, $to, $from): string
    {
        if (!\function_exists('iconv')) {
            throw new RuntimeError('Unable to convert encoding: required function iconv() does not exist. You should install ext-iconv or symfony/polyfill-iconv.');
        }

        return iconv($from, $to, $string ?? '');
    }

    /**
     * Returns the length of a variable.
     *
     * @param mixed $thing A variable
     *
     * @internal
     */
    public static function length(string $charset, $thing): int
    {
        if (null === $thing) {
            return 0;
        }

View on GitHub (pinned to a414c3a491)