apache/flink · error · IllegalStateException

The broadcast variable with name '${name}' is not a List. A

Error message

The broadcast variable with name '${name}' is not a List. A different call must have requested this variable with a BroadcastVariableInitializer.

What it means

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.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/functions/util/RuntimeUDFContext.java:105

    }

    @Override
    public boolean hasBroadcastVariable(String name) {
        return this.initializedBroadcastVars.containsKey(name)
                || this.uninitializedBroadcastVars.containsKey(name);
    }

    @Override
    @SuppressWarnings("unchecked")
    public <RT> List<RT> getBroadcastVariable(String name) {

        // check if we have an initialized version
        Object o = this.initializedBroadcastVars.get(name);
        if (o != null) {
            if (o instanceof List) {
                return (List<RT>) o;
            } else {
                throw new IllegalStateException(
                        "The broadcast variable with name '"
                                + name
                                + "' is not a List. A different call must have requested this variable with a BroadcastVariableInitializer.");
            }
        } else {
            List<?> uninitialized = this.uninitializedBroadcastVars.remove(name);
            if (uninitialized != null) {
                this.initializedBroadcastVars.put(name, uninitialized);
                return (List<RT>) uninitialized;
            } else {
                throw new IllegalArgumentException(
                        "The broadcast variable with name '" + name + "' has not been set.");
            }
        }
    }

    @SuppressWarnings("unchecked")
    @Override

View on GitHub (pinned to 2f3c205e92)

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.

Example fix

// before — conflicting access methods for same name
functionA: ctx.getBroadcastVariableWithInitializer("rules", init);
functionB: ctx.getBroadcastVariable("rules"); // throws

// after — use distinct names or consistent access
functionA: ctx.getBroadcastVariableWithInitializer("rules", init);
functionB: ctx.getBroadcastVariableWithInitializer("rules", init);

Defensive patterns

Strategy: validation

Validate before calling

// Use one access method consistently per broadcast variable name
// If you need both patterns, use different names:
operator.withBroadcastSet(setA, "rules-list");
operator.withBroadcastSet(setB, "rules-custom");

Try / catch

try {
    List<Rule> rules = getRuntimeContext().getBroadcastVariable("rules");
} catch (IllegalStateException e) {
    // Variable was stored as a custom object; use getBroadcastVariableWithInitializer instead
    RuleSet rs = getRuntimeContext().getBroadcastVariableWithInitializer("rules", init);
}

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/4a8788e8475a4c08. Report an issue: GitHub.