phalcon/cphalcon · error · Phalcon\Mvc\View\Engine\Volt\Exceptions\MbstringRequired

'mbstring' is required to perform the charset conversion

Error message

'mbstring' is required to perform the charset conversion

What it means

Volt::convertEncoding() is the engine-side implementation of the convert_encoding filter (and any charset conversion Volt performs); it hard-depends on PHP's mbstring extension via mb_convert_encoding() and throws MbstringRequired when phpFunctionExists('mb_convert_encoding') is false (phalcon/Mvc/View/Engine/Volt.zep:79). This is an environment problem, not a data problem — the filter cannot run without the extension.

Source

Thrown at phalcon/Mvc/View/Engine/Volt.zep:79

    {
        var macro;

        if unlikely !fetch macro, this->macros[name] {
            throw new MacroNotFound(name);
        }

        return call_user_func(macro, arguments);
    }

    /**
     * Performs a string conversion
     *
     * @return string
     */
    public function convertEncoding(string text,  string from,  string to) -> string
    {
        if unlikely !this->phpFunctionExists("mb_convert_encoding") {
            throw new MbstringRequired();
        }

        return mb_convert_encoding(text, to, from);
    }

    /**
     * Returns the Volt's compiler
     *
     * @return Compiler
     */
    public function getCompiler() -> <Compiler>
    {
        var compiler, container, options;

        let compiler = this->compiler;

        if typeof compiler !== "object" {
            let compiler = new Compiler(this->view);

View on GitHub (pinned to b7419de9cd)

Solutions

1. Install/enable mbstring: Debian images RUN docker-php-ext-install mbstring; RHEL/Alpine install the php-mbstring package; ensure extension=mbstring is enabled in php.ini
2. Add ext-mbstring to composer.json require so the dependency is declared
3. If mbstring is truly unavailable, pre-convert encodings in PHP before assigning to the view and drop the filter from templates

Example fix

# before (Dockerfile)
FROM php:8.3-cli-alpine
# mbstring missing -> MbstringRequired at runtime

# after
FROM php:8.3-cli-alpine
RUN docker-php-ext-install mbstring

if (!extension_loaded('mbstring')) {
    throw new \RuntimeException('ext-mbstring is required for Volt charset conversion');
}

When it happens

Trigger: A Volt template using {{ title|convert_encoding('UTF-8', 'ISO-8859-1') }} on a host where ext-mbstring is not loaded; slim PHP Docker images (php:8.*-cli / alpine variants) that exclude mbstring by default; a deployment where the mbstring ini was disabled.

Common situations: Works on the dev machine (bundled mbstring) but fails in an Alpine/slim Docker image; hosting provider disabling mbstring; upgrading the base image and losing compiled extensions.

Related errors

• {message}
• Invalid template engine registration for extension: {extensi
• Macro '{name}' does not exist
• Invalid haystack
• The extension is not valid

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/17f9e1f2b88f9ffb. Report an issue: GitHub.