{"record":{"id":"f269835e462e28cb","repo":"kestra-io/kestra","slug":"an-error-occurred-while-flattening-the-list","errorCode":null,"errorMessage":"An error occurred while flattening the list.","messagePattern":"An error occurred while flattening the list\\.","errorType":"exception","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/filters/FlattenFilter.java","lineNumber":38,"sourceCode":"\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":20,"sourceCodeEnd":42,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/filters/FlattenFilter.java#L20-L42","documentation":"Thrown by the 'flatten' Pebble filter when an unexpected exception occurs while flattening a one-level-nested List via Stream.flatMap. The input has already passed the `instanceof List` guard, so this catch-all is a defensive wrapper around the stream pipeline. The original cause is attached as the PebbleException's cause but is not surfaced in the message, making diagnosis harder.","triggerScenarios":"Calling `{{ nested | flatten }}` in a Pebble expression where a list element is a type whose stream coercion fails, or where a concurrent modification / null element breaks flatMap (e.g. a list containing a null that flatMap routes through Stream.of(null)). In practice the pipeline is robust, so this branch is rarely hit unless the input list was mutated concurrently or a custom collection throws on iteration.","commonSituations":"Outputs of tasks that return a List of Lists where the inner structure is partially null or a custom Iterable; race conditions when the same variable is read while being written by another task; passing a `null` element inside the outer list.","solutions":["Inspect the attached cause in the stack trace to identify the real failure (the message alone gives no detail).","Sanitize the list before flattening: filter nulls with `{{ nested | filter(n -> n != null) }}` if a filter is available, or pre-clean in a script task.","If you only need a shallow flatten, confirm the input is a plain List<List<?>> and not a custom collection that throws on `stream()`.","Reproduce with a unit test that prints the cause; report if the cause indicates a Kestra-side bug."],"exampleFix":"# before\n{{ outputs.transform.rows | flatten }}\n# after - guard nulls first\n{% set cleaned = outputs.transform.rows | map(v -> v ?? []) %}\n{{ cleaned | flatten }}","handlingStrategy":"try-catch","validationCode":"# In a Pebble expression, ensure the input is a List before flattening:\n{% if cleaned is iterable and cleaned is not string %}\n  {{ cleaned | flatten }}\n{% else %}\n  []\n{% endif %}","typeGuard":"# Pebble has no runtime instanceof; pre-clean in a script task:\n# List<?> safe = input == null ? List.of() : input.stream().filter(Objects::nonNull).toList();\n# then expose `safe` to the template.","tryCatchPattern":"# Pebble templates cannot try/catch; wrap the risky filter in a conditional\n# and provide a fallback value:\n{{ (nested ?? []) | flatten }}","preventionTips":["Avoid passing lists that may contain null elements to flatten; sanitize upstream.","Do not mutate the same collection from concurrent tasks while a template reads it.","Unit-test the filter chain with representative input shapes before deploying the flow."],"tags":["pebble-filter","flatten","list","stream","defensive-catch"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}