{"record":{"id":"4a8788e8475a4c08","repo":"apache/flink","slug":"the-broadcast-variable-with-name-name-is-not","errorCode":null,"errorMessage":"The broadcast variable with name '${name}' is not a List. A different call must have requested this variable with a BroadcastVariableInitializer.","messagePattern":"The broadcast variable with name '(.+?)' is not a List\\. A different call must have requested this variable with a BroadcastVariableInitializer\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/functions/util/RuntimeUDFContext.java","lineNumber":105,"sourceCode":"    }\n\n    @Override\n    public boolean hasBroadcastVariable(String name) {\n        return this.initializedBroadcastVars.containsKey(name)\n                || this.uninitializedBroadcastVars.containsKey(name);\n    }\n\n    @Override\n    @SuppressWarnings(\"unchecked\")\n    public <RT> List<RT> getBroadcastVariable(String name) {\n\n        // check if we have an initialized version\n        Object o = this.initializedBroadcastVars.get(name);\n        if (o != null) {\n            if (o instanceof List) {\n                return (List<RT>) o;\n            } else {\n                throw new IllegalStateException(\n                        \"The broadcast variable with name '\"\n                                + name\n                                + \"' is not a List. A different call must have requested this variable with a BroadcastVariableInitializer.\");\n            }\n        } else {\n            List<?> uninitialized = this.uninitializedBroadcastVars.remove(name);\n            if (uninitialized != null) {\n                this.initializedBroadcastVars.put(name, uninitialized);\n                return (List<RT>) uninitialized;\n            } else {\n                throw new IllegalArgumentException(\n                        \"The broadcast variable with name '\" + name + \"' has not been set.\");\n            }\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Override","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/functions/util/RuntimeUDFContext.java#L87-L123","documentation":"Thrown by RuntimeUDFContext.getBroadcastVariable() when the object stored under the given name is not a List. This happens when a previous call to getBroadcastVariableWithInitializer() for the same name already stored a non-List object (the result of the initializer's initializeBroadcastVariable()). The two access methods are mutually exclusive per variable name.","triggerScenarios":"A RichFunction first calls getBroadcastVariableWithInitializer(name, initializer) which stores a custom result object, then later (or in another function instance in the same task) calls getBroadcastVariable(name) expecting a List. The stored object is not a List.","commonSituations":"Two functions in the same operator chain access the same broadcast variable name, one via getBroadcastVariable() and the other via getBroadcastVariableWithInitializer(). Refactoring a function to use a custom initializer while another function in the same task still expects a List. Reusing broadcast variable names for different purposes across functions.","solutions":["Use consistent access method for a given broadcast variable name: either always getBroadcastVariable() (returns List) or always getBroadcastVariableWithInitializer() (returns custom object).","Give different broadcast variables distinct names if they have different consumption patterns.","Audit all functions in the same operator chain for broadcast variable name collisions."],"exampleFix":"// before — conflicting access methods for same name\nfunctionA: ctx.getBroadcastVariableWithInitializer(\"rules\", init);\nfunctionB: ctx.getBroadcastVariable(\"rules\"); // throws\n\n// after — use distinct names or consistent access\nfunctionA: ctx.getBroadcastVariableWithInitializer(\"rules\", init);\nfunctionB: ctx.getBroadcastVariableWithInitializer(\"rules\", init);","handlingStrategy":"validation","validationCode":"// Use one access method consistently per broadcast variable name\n// If you need both patterns, use different names:\noperator.withBroadcastSet(setA, \"rules-list\");\noperator.withBroadcastSet(setB, \"rules-custom\");","typeGuard":null,"tryCatchPattern":"try {\n    List<Rule> rules = getRuntimeContext().getBroadcastVariable(\"rules\");\n} catch (IllegalStateException e) {\n    // Variable was stored as a custom object; use getBroadcastVariableWithInitializer instead\n    RuleSet rs = getRuntimeContext().getBroadcastVariableWithInitializer(\"rules\", init);\n}","preventionTips":["Use the same access method (getBroadcastVariable or getBroadcastVariableWithInitializer) for a given broadcast variable name across all functions in the same task.","Give broadcast variables distinct names if consumed differently.","Document the intended access pattern for each broadcast variable name."],"tags":["broadcast-variable","runtime-context","type-mismatch","user-error"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}