{"record":{"id":"159c6b9a15cbc13d","repo":"kestra-io/kestra","slug":"the-subflow-function-cannot-set-the-system-label","errorCode":null,"errorMessage":"The 'subflow' function cannot set the system label '%s'; system labels are reserved (except '%s').","messagePattern":"The 'subflow' function cannot set the system label '(.+?)'; system labels are reserved \\(except '(.+?)'\\)\\.","errorType":"exception","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/functions/SubflowFunction.java","lineNumber":221,"sourceCode":"            } else {\n                DEPTH.set(current);\n            }\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private List<Label> buildLabels(Object rawLabels, PebbleTemplate self, int lineNumber) {\n        List<Label> labels = new ArrayList<>();\n        if (rawLabels != null) {\n            if (!(rawLabels instanceof Map)) {\n                throw new PebbleException(null, \"The 'subflow' function 'labels' must be a map of string keys to values.\", lineNumber, self.getName());\n            }\n            ((Map<String, Object>) rawLabels).forEach((key, value) ->\n            {\n                if (value != null) {\n                    // system labels are reserved for Kestra; only system.correlationId may be propagated by the caller\n                    if (key.startsWith(Label.SYSTEM_PREFIX) && !key.equals(Label.CORRELATION_ID)) {\n                        throw new PebbleException(\n                            null, \"The 'subflow' function cannot set the system label '\" + key + \"'; system labels are reserved (except '\" + Label.CORRELATION_ID + \"').\", lineNumber,\n                            self.getName()\n                        );\n                    }\n                    labels.add(new Label(key, String.valueOf(value)));\n                }\n            });\n        }\n        // tag the execution as run by the subflow() function (cf. the Subflow task's system.from label)\n        labels.add(new Label(Label.FROM, Label.FromLabel.SUBFLOW.value));\n        return labels;\n    }\n\n    private Duration resolveTimeout(Object rawTimeout, PebbleTemplate self, int lineNumber) {\n        Duration timeout;\n        if (rawTimeout == null) {\n            timeout = configuration.defaultTimeout();\n        } else if (rawTimeout instanceof Duration d) {","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/functions/SubflowFunction.java#L203-L239","documentation":"The subflow() function's buildLabels() helper iterates over the caller-provided labels map and rejects any key starting with the system label prefix (io.kestra prefix, defined by Label.SYSTEM_PREFIX). System labels are reserved for Kestra's internal use. The sole exception is the correlation ID label (Label.CORRELATION_ID), which callers may propagate to maintain trace correlation across the parent and child execution.","triggerScenarios":"Passing labels={'system.from': 'custom'} or any key starting with the system prefix. Attempting to set a system label like system.correlationId manually (note: correlationId is the one allowed exception, but must match the exact constant value).","commonSituations":"Trying to override or spoof system labels to influence Kestra's internal tracking. Unintentional key naming that collides with the system prefix. Copying internal label names from Kestra logs or execution details into a subflow() labels map.","solutions":["Remove any label keys starting with the system prefix from the subflow() labels map.","Use non-prefixed custom label keys instead, e.g., {'env': 'prod', 'team': 'data'}.","If you need to propagate correlation, use the exact correlation ID label constant (typically 'system.correlationId')."],"exampleFix":"# before — using a reserved system label prefix\n{{ subflow(namespace='ns', id='child', labels={'system.from': 'custom', 'system.x': 'y'}) }}\n\n# after — use custom (non-system) label keys\n{{ subflow(namespace='ns', id='child', labels={'env': 'prod', 'team': 'data'}) }}","handlingStrategy":"validation","validationCode":"# Never use system-prefixed label keys (e.g., 'system.*') in subflow() labels.\n# Only custom (non-prefixed) keys and 'system.correlationId' are allowed.\n# Correct: {{ subflow(namespace='ns', id='child', labels={'env': 'prod', 'team': 'data'}) }}\n# The only allowed system label: {'system.correlationId': outputs.parent.correlation_id}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid any label key starting with the system prefix in subflow() calls.","Use custom, non-prefixed label keys for business metadata.","Only propagate system.correlationId if you explicitly need cross-execution trace correlation.","Review label keys during code review to catch accidental system-prefix usage."],"tags":["pebble","subflow","labels","system-labels","reserved","security"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}