kestra-io/kestra · error · IllegalArgumentException

Unable to parse array element as `{}` on `{}`

Error message

Unable to parse array element as `{}` on `{}`

What it means

Thrown while recursively parsing each element of an ARRAY or MULTISELECT input/output against its declared `itemType`. When a single element cannot be coerced to that element type (e.g. a STRING declared INT, or a malformed JSON object for a RECORD), `parseType` fails and the failure is re-wrapped naming both the expected element type and the offending element value. The two placeholders are the declared `elementType` and the raw `element` that failed to parse.

Source

Thrown at core/src/main/java/io/kestra/core/runners/FlowInputOutput.java:595

                    yield current.toString();
                }
                case ARRAY, MULTISELECT -> {
                    List<?> asList;
                    if (current instanceof List<?> list) {
                        asList = list;
                    } else {
                        asList = JacksonMapper.toList(((String) current));
                    }

                    if (elementType != null) {
                        // recursively parse the elements only once
                        yield asList.stream()
                            .map(throwFunction(element ->
                            {
                                try {
                                    return parseType(execution, elementType, id, null, element, data);
                                } catch (Throwable e) {
                                    throw new IllegalArgumentException("Unable to parse array element as `" + elementType + "` on `" + element + "`", e);
                                }
                            }))
                            .toList();
                    } else {
                        yield asList;
                    }
                }
                case FORM, REUSABLE_INPUTS -> throw new IllegalStateException("FORM and REUSABLE_INPUTS inputs must be expanded before resolution");
            };
        } catch (IllegalArgumentException | ConstraintViolationException e) {
            throw e;
        } catch (Throwable e) {
            throw new Exception(" errors:\n```\n" + e.getMessage() + "\n```");
        }
    }

    private static Execution minimalExecution(FlowInterface flow, String executionId) {
        return Execution.builder()

View on GitHub (pinned to 823fada927)

Solutions

  1. Inspect the error's element value and elementType: align the submitted array entry with the declared itemType (convert the string to a number, fix the JSON object shape, etc.).
  2. If the source data is heterogeneous, change the input's `itemType` to a more permissive type (e.g. STRING or JSON) or pre-clean the data before submission.
  3. Validate the rendered array with a Pebble expression or a pre-task before it reaches the typed input.
  4. When the element is legitimately optional, mark the input `required: false` and handle nulls inside the flow.

Example fix

# before (flow input)
id: my_flow
inputs:
  - id: numbers
    type: ARRAY
    itemType: INT
# submission: {"numbers": [1, "two", 3]}

# after — coerce source data to integers before submit
#   or relax the itemType
inputs:
  - id: numbers
    type: ARRAY
    itemType: STRING
Defensive patterns

Strategy: validation

Validate before calling

// Before submitting, verify every array entry matches itemType
Object rendered = renderInput(valuesExpression);
if (rendered instanceof List<?> list) {
    for (Object e : list) {
        if (!isAssignable(elementType, e)) {
            throw new IllegalArgumentException(
                "Array entry " + e + " is not compatible with itemType " + elementType);
        }
    }
}

Type guard

static boolean isAssignable(io.kestra.core.models.tasks.runners.Type itemType, Object element) {
    return switch (itemType) {
        case INT    -> element instanceof Integer || element instanceof Long || (element instanceof String s && s.matches("-?\\d+"));
        case FLOAT  -> element instanceof Number;
        case BOOL   -> element instanceof Boolean;
        case STRING -> element instanceof CharSequence;
        default     -> true; // JSON/RECORD: accept and let Jackson validate
    };
}

Try / catch

try {
    outputs = flowInputOutput.parseExecutionInputs(flow, execution, inputs);
} catch (IllegalArgumentException e) {
    // message already names elementType + offending element
    return badRequest(e.getMessage());
}

Prevention

When it happens

Trigger: An input of type ARRAY with an `itemType` (e.g. `itemType: INT`) is submitted where at least one list entry is not coercible — e.g. values `[1, "abc", 3]` for an INT array, or a JSON object where a STRING was expected. Also triggered by a MULTISELECT whose rendered value yields mixed-type entries, or by a RECORD/JSON itemType whose element is not valid JSON for that schema.

Common situations: Submitting flow inputs via the API or UI with mismatched element types; a Pebble-rendered array expression that injects a non-numeric token into a numeric array; downstream tasks passing outputs of the wrong shape into a subflow input declared as a typed array; CSV/JSON source data containing a null or string where a number was expected.

Understand the failure class

Related errors

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