{"record":{"id":"665dab0e47937298","repo":"kestra-io/kestra","slug":"the-kv-function-expects-an-argument-key","errorCode":null,"errorMessage":"The 'kv' function expects an argument 'key'.","messagePattern":"The 'kv' function expects an argument 'key'\\.","errorType":"validation","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/functions/KvFunction.java","lineNumber":100,"sourceCode":"    }\n\n    private Optional<KVValue> getValueWithInheritance(String flowNamespace, String key, String tenantId)\n        throws IOException, ResourceExpiredException {\n        Optional<KVValue> value = Optional.empty();\n        String inheritedNamespace = flowNamespace;\n        while (value.isEmpty()) {\n            value = kvStoreService.get().get(tenantId, inheritedNamespace, flowNamespace).getValue(key);\n            if (!inheritedNamespace.contains(\".\")) {\n                return value;\n            }\n            inheritedNamespace = inheritedNamespace.substring(0, inheritedNamespace.lastIndexOf('.'));\n        }\n        return value;\n    }\n\n    protected String getKey(Map<String, Object> args, PebbleTemplate self, int lineNumber) {\n        if (!args.containsKey(KEY_ARGS)) {\n            throw new PebbleException(null, \"The 'kv' function expects an argument 'key'.\", lineNumber, self.getName());\n        }\n\n        return (String) args.get(KEY_ARGS);\n    }\n}\n","sourceCodeStart":82,"sourceCodeEnd":106,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/functions/KvFunction.java#L82-L106","documentation":"The kv() function requires a 'key' argument. If the Pebble expression omits the key parameter entirely (the args map does not contain a 'key' entry), this error fires immediately before any KV store access. This is purely a template-authoring contract violation.","triggerScenarios":"Calling {{ kv() }} with no arguments. Calling {{ kv(namespace='company.team') }} with only a namespace and no key. Passing arguments in a way Pebble does not bind to the 'key' parameter name.","commonSituations":"The flow author forgot to include the key. The author used a dynamic expression for the key that resolved to nothing (e.g. {{ kv(myVar) }} where myVar is null and Pebble maps it positionally but the positional arg is not bound to 'key').","solutions":["Always pass the key argument: {{ kv('myKey') }} or {{ kv(key='myKey') }}.","If the key is dynamic, ensure the variable is a non-null string at render time."],"exampleFix":"# before\nvalue: \"{{ kv(namespace='company.team') }}\"\n# after\nvalue: \"{{ kv('myKey', namespace='company.team') }}\"","handlingStrategy":"validation","validationCode":"# Always pass the key argument positionally or by name:\n{{ kv('myKey') }}\n{{ kv(key='myKey', namespace='company.team') }}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the key argument when calling kv().","Use named parameters in complex expressions to avoid ambiguity.","Lint flow YAML templates to verify all required Pebble function arguments are present."],"tags":["pebble-function","kv-store","missing-argument"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}