apache/flink · error · IllegalArgumentException

The broadcast variable with name '${name}' has not been set.

Error message

The broadcast variable with name '${name}' has not been set.

What it means

Thrown by RuntimeUDFContext.getBroadcastVariable() when no broadcast variable has been registered under the given name. The variable was not provided via withBroadcastSet() on the operator. The exception fires because neither the initialized nor uninitialized broadcast-variable maps contain the name.

Source

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

        // 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
    public <T, C> C getBroadcastVariableWithInitializer(
            String name, BroadcastVariableInitializer<T, C> initializer) {

        // check if we have an initialized version
        Object o = this.initializedBroadcastVars.get(name);
        if (o != null) {
            return (C) o;
        } else {
            List<T> uninitialized = (List<T>) this.uninitializedBroadcastVars.remove(name);
            if (uninitialized != null) {
                C result = initializer.initializeBroadcastVariable(uninitialized);

View on GitHub (pinned to 2f3c205e92)

Solutions

Register the broadcast set on the operator: operator.withBroadcastSet(broadcastDataSet, name) using the exact same name string.
Double-check the name spelling and case in both the registration and the getBroadcastVariable() call.
Ensure the broadcast DataSet is non-empty and is actually part of the job graph.

Example fix

// before
DataSet<Integer> rules = env.fromElements(1, 2, 3);
input.map(new MyMapper()); // calls getBroadcastVariable("rules") but not registered

// after
input.map(new MyMapper()).withBroadcastSet(rules, "rules");

Defensive patterns

Strategy: validation

Validate before calling

// Ensure withBroadcastSet() is called with the exact name
DataSet<MyData> broadcastData = ...;
input.map(new MyMapper())
     .withBroadcastSet(broadcastData, "myRules"); // must match getBroadcastVariable("myRules")

Prevention

Always call withBroadcastSet(dataSet, name) for each broadcast variable the function accesses.
Use a constant or enum for broadcast variable names to avoid typos.
Verify the name string matches exactly (case-sensitive) in registration and access.

When it happens

Trigger: A RichFunction calls getRuntimeContext().getBroadcastVariable(name) but the upstream pipeline did not call .withBroadcastSet(dataSet, name) to register that broadcast set. The name does not match what was registered.

Common situations: Typo in the broadcast variable name string. Forgot to call withBroadcastSet(). The broadcast DataSet was filtered out or optimized away. Using broadcast variables in a streaming context where they are not supported without broadcast state patterns.

Related errors

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