{"record":{"id":"5d4e62d2228cb278","repo":"twigphp/Twig","slug":"variables-passed-to-the-with-tag-must-be-a-mapping","errorCode":null,"errorMessage":"Variables passed to the \"with\" tag must be a mapping.","messagePattern":"Variables passed to the \"with\" tag must be a mapping\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/Node/WithNode.php","lineNumber":52,"sourceCode":"\n    public function compile(Compiler $compiler): void\n    {\n        $compiler->addDebugInfo($this);\n\n        $parentContextName = $compiler->getVarName();\n\n        $compiler->write(\\sprintf(\"\\$%s = \\$context;\\n\", $parentContextName));\n\n        if ($this->hasNode('variables')) {\n            $node = $this->getNode('variables');\n            $varsName = $compiler->getVarName();\n            $compiler\n                ->write(\\sprintf('$%s = ', $varsName))\n                ->subcompile($node)\n                ->raw(\";\\n\")\n                ->write(\\sprintf(\"if (!is_iterable(\\$%s)) {\\n\", $varsName))\n                ->indent()\n                ->write(\"throw new RuntimeError('Variables passed to the \\\"with\\\" tag must be a mapping.', \")\n                ->repr($node->getTemplateLine())\n                ->raw(\", \\$this->getSourceContext());\\n\")\n                ->outdent()\n                ->write(\"}\\n\")\n                ->write(\\sprintf(\"\\$%s = CoreExtension::toArray(\\$%s);\\n\", $varsName, $varsName))\n            ;\n\n            if ($this->getAttribute('only')) {\n                $compiler->write(\"\\$context = [];\\n\");\n            }\n\n            $compiler->write(\\sprintf(\"\\$context = \\$%s + \\$context + \\$this->env->getGlobals();\\n\", $varsName));\n        }\n\n        $compiler\n            ->subcompile($this->getNode('body'))\n            ->write(\\sprintf(\"\\$context = \\$%s;\\n\", $parentContextName))\n        ;","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/twigphp/Twig/blob/a414c3a491defb5a60f2fc88ef79ff37c90010cd/src/Node/WithNode.php#L34-L70","documentation":"The {% with %} tag's compiled code evaluates the passed variables and requires an iterable mapping before converting it via CoreExtension::toArray(). Scalars like strings or integers passed to with are rejected at runtime with this RuntimeError.","triggerScenarios":"{% with foo %}...{% endwith %} or {% with someString %} where the expression is not an array/object (e.g. a string, number, or boolean).","commonSituations":"Passing a scalar by mistake instead of a hash; a variable expected to be an array being null/string due to upstream data issues.","solutions":["Pass a hash: {% with { foo: bar } %}...{% endwith %}","Guard the value: only enter the with-block when the variable is an array","Fix upstream data so the variable is a mapping"],"exampleFix":"// before\n{% with settings_string %}...{% endwith %}\n// after\n{% with { settings: settings_string } %}...{% endwith %}","handlingStrategy":"type-guard","validationCode":"if (!is_iterable($vars) && !is_array($vars)) {\n    throw new InvalidArgumentException('{% with %} requires a mapping');\n}","typeGuard":"function isMapping(mixed $v): bool {\n    return is_array($v) || $v instanceof \\Traversable;\n}","tryCatchPattern":"try {\n    $twig->render($template, $context);\n} catch (\\Twig\\Error\\RuntimeError $e) {\n    if (str_contains($e->getMessage(), 'must be a mapping')) {\n        // coerce/fix the variable passed to {% with %}\n    }\n    throw $e;\n}","preventionTips":["Always pass hashes to {% with %}: { key: value }","Validate upstream data shapes before render","Coerce scalars to arrays at the controller layer"],"tags":["twig","with-tag","runtime","type-error"],"backgroundTag":"type-mismatch","analyzedSha":"a414c3a491defb5a60f2fc88ef79ff37c90010cd","analyzedAt":"2026-09-13T15:10:46.849Z","contentChangedAt":"2026-09-13T15:10:46.849Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}