What causes "An error occurred while flattening the list." in kestra-io/kestra?

Inspect the attached cause in the stack trace to identify the real failure (the message alone gives no detail).

kestra-io/kestra · error · PebbleException

An error occurred while flattening the list.

Error message

An error occurred while flattening the list.

What it means

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.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/filters/FlattenFilter.java:38

    @Override
    public Object apply(Object input, Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) throws PebbleException {
        if (input == null) {
            return null;
        }

        if (!(input instanceof List)) {
            throw new PebbleException(null, "The 'flatten' filter can only be applied to lists.", lineNumber, self.getName());
        }

        try {
            List<?> list = (List<?>) input;
            List<Object> flattened = list.stream()
                .flatMap(o -> o instanceof List<?> listValue ? listValue.stream() : Stream.of(o))
                .toList();
            return flattened;
        } catch (Exception e) {
            throw new PebbleException(e, "An error occurred while flattening the list.", lineNumber, self.getName());
        }
    }
}

View on GitHub (pinned to 823fada927)

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.

Example fix

# before
{{ outputs.transform.rows | flatten }}
# after - guard nulls first
{% set cleaned = outputs.transform.rows | map(v -> v ?? []) %}
{{ cleaned | flatten }}

Defensive patterns

Strategy: try-catch

Validate before calling

# In a Pebble expression, ensure the input is a List before flattening:
{% if cleaned is iterable and cleaned is not string %}
  {{ cleaned | flatten }}
{% else %}
  []
{% endif %}

Type guard

# Pebble has no runtime instanceof; pre-clean in a script task:
# List<?> safe = input == null ? List.of() : input.stream().filter(Objects::nonNull).toList();
# then expose `safe` to the template.

Try / catch

# Pebble templates cannot try/catch; wrap the risky filter in a conditional
# and provide a fallback value:
{{ (nested ?? []) | flatten }}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/f269835e462e28cb. Report an issue: GitHub.