kestra-io/kestra · error · PebbleException

The 'tasksWithState' function expects an argument 'state'.

Error message

The 'tasksWithState' function expects an argument 'state'.

What it means

The Pebble `tasksWithState()` function requires a single argument named `state`. The function checks `args.containsKey("state")` at the top of `execute()` and throws if it is absent. This is a template-authoring error indicating the function was called without its sole parameter.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/TasksWithStateFunction.java:28

import io.pebbletemplates.pebble.template.EvaluationContextImpl;
import io.pebbletemplates.pebble.template.PebbleTemplate;

public class TasksWithStateFunction implements KestraFunction {
    public static final String NAME = "tasksWithState";

    public List<String> getArgumentNames() {
        return List.of("state");
    }

    @Override
    public Map<String, String> getArgumentDefaults() {
        return Map.of("state", "'FAILED'");
    }

    @Override
    public Object execute(Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
        if (!args.containsKey("state")) {
            throw new PebbleException(null, "The 'tasksWithState' function expects an argument 'state'.", lineNumber, self.getName());
        }
        String stateToFilter = ((String) args.get("state")).toUpperCase();

        EvaluationContextImpl evaluationContext = (EvaluationContextImpl) context;

        Map<String, Object> globalTasksMap = (Map<String, Object>) evaluationContext.getScopeChain().getGlobalScopes().stream()
            .flatMap(scope -> scope.getKeys().stream())
            .distinct()
            .filter(key -> "tasks".equals(key)) // Filter for the "tasks" key specifically
            .collect(HashMap::new, (m, k) -> m.put(k, context.getVariable(k)), HashMap::putAll)
            .get("tasks");

        List<Map<String, Object>> filteredTasks = new ArrayList<>();

        if (globalTasksMap != null) {
            globalTasksMap.forEach((taskId, taskDetailsObj) ->
            {
                if (taskDetailsObj instanceof Map) {

View on GitHub (pinned to 823fada927)

Solutions

Provide the `state` argument explicitly: `tasksWithState(state='FAILED')`.
Check that the argument name is exactly `state` (case-sensitive).
Note the default value is `'FAILED'`, but the key must still be present in args.

Example fix

# before
{{ tasksWithState() }}
# after
{{ tasksWithState(state='FAILED') }}

Defensive patterns

Strategy: validation

Validate before calling

# Pebble template: always pass the state argument explicitly
{{ tasksWithState(state='FAILED') }}
{{ tasksWithState(state='SUCCESS') }}

Prevention

Always provide the named argument: tasksWithState(state='...').
Use a linter or template validator to check required Pebble function arguments.

When it happens

Trigger: Calling `tasksWithState()` with no arguments. Calling it with a differently-named argument. The Pebble engine only populates `args` with explicitly named arguments that are present in the call.

Common situations: A developer forgets the argument or uses the wrong name. The function signature changed in a version upgrade and old templates are incompatible.

Related errors

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