{"record":{"id":"a16d6ca6fc6ecd3e","repo":"kestra-io/kestra","slug":"the-key-key-does-not-exist-in-the-namespace","errorCode":null,"errorMessage":"The key '{key}' does not exist in the namespace '{namespace}'.","messagePattern":"The key '(.+?)' does not exist in the namespace '(.+?)'\\.","errorType":"exception","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/functions/KvFunction.java","lineNumber":78,"sourceCode":"        try {\n            if (namespace == null) {\n                namespace = flowNamespace;\n                value = getValueWithInheritance(flowNamespace, key, flowTenantId);\n            } else {\n                // we didn't check allowedNamespace here as it's checked in the kvStoreService itself\n                value = kvStoreService.get().get(flowTenantId, namespace, flowNamespace).getValue(key);\n            }\n        } catch (ResourceExpiredException e) {\n            if (errorOnMissing) {\n                throw new PebbleException(e, e.getMessage(), lineNumber, self.getName());\n            }\n            value = Optional.empty();\n        } catch (Exception e) {\n            throw new PebbleException(e, e.getMessage(), lineNumber, self.getName());\n        }\n\n        if (value.isEmpty() && errorOnMissing) {\n            throw new PebbleException(null, \"The key '\" + key + \"' does not exist in the namespace '\" + namespace + \"'.\", lineNumber, self.getName());\n        }\n\n        return value.map(KVValue::value).orElse(null);\n    }\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    }","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/functions/KvFunction.java#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set errorOnMissing=false if a missing key is an acceptable (nullable) condition: {{ kv('myKey', errorOnMissing=false) }}.","Verify the key exists using the KV store API or UI: GET /api/v1/namespaces/{namespace}/kv.","Check for typos and casing in the key name and confirm the correct namespace."],"exampleFix":"# before\nvalue: \"{{ kv('apiToken') }}\"\n# after (tolerate missing key)\nvalue: \"{{ kv('apiToken', errorOnMissing=false) }}\"","handlingStrategy":"validation","validationCode":"# Set errorOnMissing=false when a missing key is acceptable:\n{{ kv('myKey', errorOnMissing=false) }}\n\n# Or check key existence via the KV API task before referencing:\nid: checkKey\ntype: io.kestra.plugin.core.kv.Get\nkey: myKey\nnamespace: company.team\nerrorOnMissing: false","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use errorOnMissing=false for optional configuration values.","Run setup flows that provision required KV keys before dependent flows execute.","Double-check key names for typos and casing — KV keys are case-sensitive."],"tags":["pebble-function","kv-store","key-not-found"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}