kestra-io/kestra · error · PebbleException

The key '{key}' does not exist in the namespace '{namespace}

Error message

The key '{key}' does not exist in the namespace '{namespace}'.

What it means

The kv() function is called with errorOnMissing=true (the default). The key was not found in the KV store for the given namespace — either the key was never set, was deleted, or (when no namespace is provided) was not found through the full namespace inheritance chain (company.team.sub → company.team → company). This fires only when the value Optional is empty after all lookup attempts.

Source

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

        try {
            if (namespace == null) {
                namespace = flowNamespace;
                value = getValueWithInheritance(flowNamespace, key, flowTenantId);
            } else {
                // we didn't check allowedNamespace here as it's checked in the kvStoreService itself
                value = kvStoreService.get().get(flowTenantId, namespace, flowNamespace).getValue(key);
            }
        } catch (ResourceExpiredException e) {
            if (errorOnMissing) {
                throw new PebbleException(e, e.getMessage(), lineNumber, self.getName());
            }
            value = Optional.empty();
        } catch (Exception e) {
            throw new PebbleException(e, e.getMessage(), lineNumber, self.getName());
        }

        if (value.isEmpty() && errorOnMissing) {
            throw new PebbleException(null, "The key '" + key + "' does not exist in the namespace '" + namespace + "'.", lineNumber, self.getName());
        }

        return value.map(KVValue::value).orElse(null);
    }

    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;
    }

View on GitHub (pinned to 823fada927)

Solutions

1. Set errorOnMissing=false if a missing key is an acceptable (nullable) condition: {{ kv('myKey', errorOnMissing=false) }}.
2. Verify the key exists using the KV store API or UI: GET /api/v1/namespaces/{namespace}/kv.
3. Check for typos and casing in the key name and confirm the correct namespace.

Example fix

# before
value: "{{ kv('apiToken') }}"
# after (tolerate missing key)
value: "{{ kv('apiToken', errorOnMissing=false) }}"

# Set errorOnMissing=false when a missing key is acceptable:
{{ kv('myKey', errorOnMissing=false) }}

# Or check key existence via the KV API task before referencing:
id: checkKey
type: io.kestra.plugin.core.kv.Get
key: myKey
namespace: company.team
errorOnMissing: false

When it happens

Trigger: Calling {{ kv('myKey') }} when 'myKey' has never been written. Calling {{ kv('myKey', namespace='company.other') }} when the key does not exist in that namespace. The key was deleted by another flow.

Common situations: A flow depends on a KV value that is provisioned by a separate setup flow that has not been run yet. The key name has a typo or uses different casing. The key was set in a different namespace.

Related errors

• {e.getMessage()}
• The 'kv' function expects an argument 'key'.
• The 'isPublicHoliday()' function could not parse 'date': {e.
• The 'isWeekend()' function expects a 'date' argument.
• The 'isWeekend()' function could not parse 'date': {e.getMes

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