{"record":{"id":"583e2a72c4736316","repo":"kestra-io/kestra","slug":"the-jq-filter-expects-an-argument-expression","errorCode":null,"errorMessage":"The 'jq' filter expects an argument 'expression'.","messagePattern":"The 'jq' filter expects an argument 'expression'\\.","errorType":"validation","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/filters/JqFilter.java","lineNumber":48,"sourceCode":"    }\n\n    public JqFilter() {\n        this.argumentNames.add(\"expression\");\n    }\n\n    @Override\n    public List<String> getArgumentNames() {\n        return this.argumentNames;\n    }\n\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 (!args.containsKey(\"expression\")) {\n            throw new PebbleException(null, \"The 'jq' filter expects an argument 'expression'.\", lineNumber, self.getName());\n        }\n\n        String pattern = (String) args.get(\"expression\");\n\n        try {\n            JsonQuery q = JsonQuery.compile(pattern, Versions.JQ_1_6);\n\n            JsonNode in;\n            if (input instanceof String stringValue) {\n                in = JacksonMapper.ofJson().readTree(stringValue);\n            } else {\n                in = JacksonMapper.ofJson().valueToTree(input);\n            }\n\n            final List<Object> out = new ArrayList<>();\n\n            try {\n                q.apply(Scope.newChildScope(SCOPE), in, v ->","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/filters/JqFilter.java#L30-L66","documentation":"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.","triggerScenarios":"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=\".\")`).","commonSituations":"Adapting examples from other template engines that pass jq positionally; copy-paste typos; refactoring a flow and dropping the argument.","solutions":["Provide the named argument: `{{ json | jq(expression=\".field\") }}`.","Verify the spelling is exactly `expression` (singular).","Check the Kestra jq filter docs for supported jq 1.6 syntax.","Validate the expression in a jq playground before embedding it."],"exampleFix":"# before\n{{ outputs.fetch.value | jq }}\n# after\n{{ outputs.fetch.value | jq(expression=\".[].id\") }}","handlingStrategy":"validation","validationCode":"# Always pass the named argument explicitly:\n{{ json | jq(expression=\".\") }}\n# If the pattern is dynamic, default it:\n{{ json | jq(expression=inputs.expr ?? \".\") }}","typeGuard":"# Pebble: guard against a null pattern before calling jq\n{% if inputs.expr is not null %}\n  {{ json | jq(expression=inputs.expr) }}\n{% endif %}","tryCatchPattern":null,"preventionTips":["Always pass `expression` as a named argument when calling the jq filter.","Lint flows for filter calls missing declared arguments.","Keep a curated snippet library of valid jq filter invocations."],"tags":["pebble-filter","jq","missing-argument","json"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}