kestra-io/kestra · error · PebbleException

The 'kv' function expects an argument 'key'.

Error message

The 'kv' function expects an argument 'key'.

What it means

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.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/KvFunction.java:100

    }

    private Optional<KVValue> getValueWithInheritance(String flowNamespace, String key, String tenantId)
        throws IOException, ResourceExpiredException {
        Optional<KVValue> value = Optional.empty();
        String inheritedNamespace = flowNamespace;
        while (value.isEmpty()) {
            value = kvStoreService.get().get(tenantId, inheritedNamespace, flowNamespace).getValue(key);
            if (!inheritedNamespace.contains(".")) {
                return value;
            }
            inheritedNamespace = inheritedNamespace.substring(0, inheritedNamespace.lastIndexOf('.'));
        }
        return value;
    }

    protected String getKey(Map<String, Object> args, PebbleTemplate self, int lineNumber) {
        if (!args.containsKey(KEY_ARGS)) {
            throw new PebbleException(null, "The 'kv' function expects an argument 'key'.", lineNumber, self.getName());
        }

        return (String) args.get(KEY_ARGS);
    }
}

View on GitHub (pinned to 823fada927)

Solutions

1. Always pass the key argument: {{ kv('myKey') }} or {{ kv(key='myKey') }}.
2. If the key is dynamic, ensure the variable is a non-null string at render time.

Example fix

# before
value: "{{ kv(namespace='company.team') }}"
# after
value: "{{ kv('myKey', namespace='company.team') }}"

# Always pass the key argument positionally or by name:
{{ kv('myKey') }}
{{ kv(key='myKey', namespace='company.team') }}

When it happens

Trigger: 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.

Common situations: 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').

Related errors

• The 'isWeekend()' function expects a 'date' argument.
• {e.getMessage()}
• The key '{key}' does not exist in the namespace '{namespace}
• The 'loopOutputs' function expects a non-null argument 'outp
• The 'loopOutputs' function expects a non-null argument 'name

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