{"record":{"id":"b46735ce02aeaf19","repo":"twigphp/Twig","slug":"the-replace-filter-expects-a-sequence-or-a-mapping-got-s","errorCode":null,"errorMessage":"The \"replace\" filter expects a sequence or a mapping, got \"%s\".","messagePattern":"The \"replace\" filter expects a sequence or a mapping, got \"(.+?)\"\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/Extension/CoreExtension.php","lineNumber":652,"sourceCode":"        if (false !== $timezone) {\n            $date->setTimezone($timezone);\n        }\n\n        return $date;\n    }\n\n    /**\n     * Replaces strings within a string.\n     *\n     * @param string|null        $str  String to replace in\n     * @param array|\\Traversable $from Replace values\n     *\n     * @internal\n     */\n    public static function replace($str, $from): string\n    {\n        if (!is_iterable($from)) {\n            throw new RuntimeError(\\sprintf('The \"replace\" filter expects a sequence or a mapping, got \"%s\".', get_debug_type($from)));\n        }\n\n        return strtr($str ?? '', self::toArray($from));\n    }\n\n    /**\n     * Rounds a number.\n     *\n     * @param int|float|string|null   $value     The value to round\n     * @param int|float               $precision The rounding precision\n     * @param 'common'|'ceil'|'floor' $method    The method to use for rounding\n     *\n     * @return float The rounded number\n     *\n     * @internal\n     */\n    public static function round($value, $precision = 0, $method = 'common')\n    {","sourceCodeStart":634,"sourceCodeEnd":670,"githubUrl":"https://github.com/twigphp/Twig/blob/a414c3a491defb5a60f2fc88ef79ff37c90010cd/src/Extension/CoreExtension.php#L634-L670","documentation":"The Twig `replace` filter calls CoreExtension::replace, which requires the second argument (`from`) to be iterable — a sequence (array) or a mapping of search=>replace pairs, passed to strtr(). If the argument is a scalar, null, or object that is not Traversable/Array, a Twig\\Error::RuntimeError is thrown naming the actual PHP debug type.","triggerScenarios":"Calling {{ 'abc'|replace(x) }} where x is a string, integer, boolean, null, or a non-Traversable object instead of an array or Traversable; also when a variable that was expected to be an array is actually null (e.g. missing context var or a function returning null).","commonSituations":"Passing a plain string like {{ 'a-b'|replace('-': '_') }}-style mistakes with wrong filter syntax; passing null because an upstream variable was unset; passing an stdClass result from json_decode without assoc=true; assuming another filter (e.g. split) returned an array but it returned null on failure.","solutions":["Make the second argument an array or mapping, e.g. {{ 'a-b'|replace({'-': '_'}) }}.","Dump the variable ({{ dump(x) }}) and check its debug type in the message to find where it became non-iterable.","If the value may be null, default it first: {{ 'abc'|replace(x|default({})) }}.","Cast Traversable to array with iterator_to_array or the |column/filter family when appropriate before replacing."],"exampleFix":"// before (template)\n{{ 'hello world'|replace(' ') }}\n\n// after\n{{ 'hello world'|replace({' ': '_'}) }}","handlingStrategy":"validation","validationCode":"// Twig template\n{% if x is iterable %}{{ str|replace(x) }}{% else %}{{ str }}{% endif %}\n\n// PHP before calling the filter\necho \\is_iterable($from) ? \\Twig\\Extension\\CoreExtension::replace($str, $from) : $str;","typeGuard":"function isReplaceSource($v): bool { return \\is_iterable($v); }","tryCatchPattern":"try {\n    $out = \\Twig\\Extension\\CoreExtension::replace($str, $from);\n} catch (\\Twig\\Error\\RuntimeError $e) {\n    $out = $str; // or log and rethrow\n}","preventionTips":["Always pass mapping literals like {'search': 'replace'} to replace.","Use |default({}) for possibly-null variables.","Verify variable types with the dump() function during development.","Remember json_decode must use assoc=true (or objects must be Traversable) before use in Twig filters."],"tags":["twig","filter","type-error","replace"],"backgroundTag":"invalid-argument-value","analyzedSha":"a414c3a491defb5a60f2fc88ef79ff37c90010cd","analyzedAt":"2026-09-13T15:10:46.849Z","contentChangedAt":"2026-09-13T15:10:46.849Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}