{"record":{"id":"17f9e1f2b88f9ffb","repo":"phalcon/cphalcon","slug":"mbstring-is-required-to-perform-the-charset-conv","errorCode":null,"errorMessage":"'mbstring' is required to perform the charset conversion","messagePattern":"'mbstring' is required to perform the charset conversion","errorType":"exception","errorClass":"Phalcon\\Mvc\\View\\Engine\\Volt\\Exceptions\\MbstringRequired","httpStatus":null,"severity":"error","filePath":"phalcon/Mvc/View/Engine/Volt.zep","lineNumber":79,"sourceCode":"    {\n        var macro;\n\n        if unlikely !fetch macro, this->macros[name] {\n            throw new MacroNotFound(name);\n        }\n\n        return call_user_func(macro, arguments);\n    }\n\n    /**\n     * Performs a string conversion\n     *\n     * @return string\n     */\n    public function convertEncoding(string text,  string from,  string to) -> string\n    {\n        if unlikely !this->phpFunctionExists(\"mb_convert_encoding\") {\n            throw new MbstringRequired();\n        }\n\n        return mb_convert_encoding(text, to, from);\n    }\n\n    /**\n     * Returns the Volt's compiler\n     *\n     * @return Compiler\n     */\n    public function getCompiler() -> <Compiler>\n    {\n        var compiler, container, options;\n\n        let compiler = this->compiler;\n\n        if typeof compiler !== \"object\" {\n            let compiler = new Compiler(this->view);","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Mvc/View/Engine/Volt.zep#L61-L97","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Add ext-mbstring to composer.json require so the dependency is declared","If mbstring is truly unavailable, pre-convert encodings in PHP before assigning to the view and drop the filter from templates"],"exampleFix":"# before (Dockerfile)\nFROM php:8.3-cli-alpine\n# mbstring missing -> MbstringRequired at runtime\n\n# after\nFROM php:8.3-cli-alpine\nRUN docker-php-ext-install mbstring","handlingStrategy":"validation","validationCode":"if (!extension_loaded('mbstring')) {\n    throw new \\RuntimeException('ext-mbstring is required for Volt charset conversion');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Declare ext-mbstring in composer.json require","docker-php-ext-install mbstring in custom images","Check extension_loaded('mbstring') in a deployment health check"],"tags":["phalcon","volt","mbstring","php-extensions","encoding","docker"],"backgroundTag":"missing-php-extension","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}