{"record":{"id":"0eef0020fb85b824","repo":"kestra-io/kestra","slug":"the-flatten-filter-can-only-be-applied-to-lists","errorCode":null,"errorMessage":"The 'flatten' filter can only be applied to lists.","messagePattern":"The 'flatten' filter can only be applied to lists\\.","errorType":"validation","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/filters/FlattenFilter.java","lineNumber":28,"sourceCode":"import io.pebbletemplates.pebble.template.EvaluationContext;\nimport io.pebbletemplates.pebble.template.PebbleTemplate;\n\npublic class FlattenFilter implements Filter {\n    private final List<String> argumentNames = new ArrayList<>();\n\n    @Override\n    public List<String> getArgumentNames() {\n        return this.argumentNames;\n    }\n\n    @Override\n    public Object apply(Object input, Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) throws PebbleException {\n        if (input == null) {\n            return null;\n        }\n\n        if (!(input instanceof List)) {\n            throw new PebbleException(null, \"The 'flatten' filter can only be applied to lists.\", lineNumber, self.getName());\n        }\n\n        try {\n            List<?> list = (List<?>) input;\n            List<Object> flattened = list.stream()\n                .flatMap(o -> o instanceof List<?> listValue ? listValue.stream() : Stream.of(o))\n                .toList();\n            return flattened;\n        } catch (Exception e) {\n            throw new PebbleException(e, \"An error occurred while flattening the list.\", lineNumber, self.getName());\n        }\n    }\n}\n","sourceCodeStart":10,"sourceCodeEnd":42,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/filters/FlattenFilter.java#L10-L42","documentation":"Thrown by the FlattenFilter when the input is not null but is not a List. The flatten filter collapses one level of nested lists into a single flat list; it cannot operate on strings, maps, numbers, or other non-list types.","triggerScenarios":"Calling flatten on a non-list value: '{{ mystring | flatten }}', '{{ mymap | flatten }}', '{{ 42 | flatten }}'. The input variable resolves to a type other than List at runtime.","commonSituations":"A task output that is sometimes a list of lists and sometimes a single value or string. Passing a JSON object where a JSON array was expected. Template logic that assumes nested-list structure from an output that is not guaranteed to be a list.","solutions":["Ensure the input is a list before calling flatten.","Wrap non-list values: '{{ [myvalue] | flatten }}'.","Add a type check or conditional to only apply flatten when the value is a list."],"exampleFix":"{# before #}\n{{ outputs.task.value | flatten }}\n{# outputs.task.value is a map #}\n\n{# after — ensure list #}\n{{ [outputs.task.value] | flatten }}","handlingStrategy":"type-guard","validationCode":"{# Ensure the input is a list before calling flatten #}\n{% set input = outputs.task.value %}\n{% if input is iterable %}\n  {{ input | flatten }}\n{% else %}\n  {{ [input] | flatten }}\n{% endif %}","typeGuard":"{# Pebble 'is iterable' narrows to list-like types #}\n{% if myvar is iterable %}\n  {{ myvar | flatten }}\n{% endif %}","tryCatchPattern":null,"preventionTips":["Verify task outputs are lists before applying flatten.","Wrap single values in a list when needed.","Add a conditional type check before calling list-only filters."],"tags":["pebble","flatten-filter","type-mismatch","list"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}