kestra-io/kestra · error · PebbleException

The 'jq' filter expects an argument 'expression'.

Error message

The 'jq' filter expects an argument 'expression'.

What it means

Thrown by the 'jq' Pebble filter when the `expression` argument is missing from the call. JqFilter declares `expression` as its only declared argument name and explicitly checks `args.containsKey("expression")` before compiling the JsonQuery. Without it there is no query to run, so the filter fails fast.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/filters/JqFilter.java:48

    }

    public JqFilter() {
        this.argumentNames.add("expression");
    }

    @Override
    public List<String> getArgumentNames() {
        return this.argumentNames;
    }

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

        if (!args.containsKey("expression")) {
            throw new PebbleException(null, "The 'jq' filter expects an argument 'expression'.", lineNumber, self.getName());
        }

        String pattern = (String) args.get("expression");

        try {
            JsonQuery q = JsonQuery.compile(pattern, Versions.JQ_1_6);

            JsonNode in;
            if (input instanceof String stringValue) {
                in = JacksonMapper.ofJson().readTree(stringValue);
            } else {
                in = JacksonMapper.ofJson().valueToTree(input);
            }

            final List<Object> out = new ArrayList<>();

            try {
                q.apply(Scope.newChildScope(SCOPE), in, v ->

View on GitHub (pinned to 823fada927)

Solutions

1. Provide the named argument: `{{ json | jq(expression=".field") }}`.
2. Verify the spelling is exactly `expression` (singular).
3. Check the Kestra jq filter docs for supported jq 1.6 syntax.
4. Validate the expression in a jq playground before embedding it.

Example fix

# before
{{ outputs.fetch.value | jq }}
# after
{{ outputs.fetch.value | jq(expression=".[].id") }}

# Always pass the named argument explicitly:
{{ json | jq(expression=".") }}
# If the pattern is dynamic, default it:
{{ json | jq(expression=inputs.expr ?? ".") }}

# Pebble: guard against a null pattern before calling jq
{% if inputs.expr is not null %}
  {{ json | jq(expression=inputs.expr) }}
{% endif %}

When it happens

Trigger: Writing `{{ json | jq }}` or `{{ json | jq() }}` without the named argument, or using a positional argument when the filter expects the named form `jq(expression="...")`. Also occurs if the argument key is misspelled (e.g. `jq(expr=".")`).

Common situations: Adapting examples from other template engines that pass jq positionally; copy-paste typos; refactoring a flow and dropping the argument.

Related errors

• Unable to parse jq value '{}' with type '{}'
• The argument 'regex' is required.
• The argument 'regex' is required.
• The argument ''{0}'' is required.
• The argument ''{0}'' is required.

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