apache/flink · error · IllegalArgumentException

The broadcast input name may not be null.

Error message

The broadcast input name may not be null.

What it means

Thrown by AbstractUdfOperator.setBroadcastVariable(String name, Operator<?> root) when the name argument is null. Broadcast variable names are keys in the broadcastInputs map; a null key would break lookup and iteration, so the API rejects it early with an IllegalArgumentException.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/operators/AbstractUdfOperator.java:92

    /**
     * Returns the input, or null, if none is set.
     *
     * @return The broadcast input root operator.
     */
    public Map<String, Operator<?>> getBroadcastInputs() {
        return this.broadcastInputs;
    }

    /**
     * Binds the result produced by a plan rooted at {@code root} to a variable used by the UDF
     * wrapped in this operator.
     *
     * @param root The root of the plan producing this input.
     */
    public void setBroadcastVariable(String name, Operator<?> root) {
        if (name == null) {
            throw new IllegalArgumentException("The broadcast input name may not be null.");
        }
        if (root == null) {
            throw new IllegalArgumentException(
                    "The broadcast input root operator may not be null.");
        }

        this.broadcastInputs.put(name, root);
    }

    /**
     * Clears all previous broadcast inputs and binds the given inputs as broadcast variables of
     * this operator.
     *
     * @param inputs The {@code<name, root>} pairs to be set as broadcast inputs.
     */
    public <T> void setBroadcastVariables(Map<String, Operator<T>> inputs) {
        this.broadcastInputs.clear();
        this.broadcastInputs.putAll(inputs);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Ensure the broadcast variable name string is non-null before calling setBroadcastVariable(). Validate or default the name.
2. If using the high-level API (withBroadcastSet(dataSet, "name")), verify the string literal is never null.
3. If the name comes from dynamic input (config, map key), add a null check and provide a meaningful default or fail with a clearer upstream error.

Example fix

// before
op.setBroadcastVariable(name, root);  // name may be null
// after
if (name == null) {
    throw new IllegalArgumentException("broadcast name must not be null for operator " + op.getName());
}
op.setBroadcastVariable(name, root);

if (name == null) {
    throw new IllegalArgumentException("Broadcast variable name must not be null");
}
op.setBroadcastVariable(name, root);

When it happens

Trigger: Calling setBroadcastVariable(null, someOperator) directly, or passing a variable that was computed (e.g., from a map lookup) and turned out null. In programmatic plan construction (rare for end users, more common in internal operator wiring), a null name string is passed.

Common situations: This is an @Internal API rarely called directly by application developers. It is hit when building operator plans programmatically at the low-level operator layer rather than using the higher-level DataSet/DataStream API, or in tests that construct operator graphs manually.

Related errors

• The broadcast input root operator may not be null.
• Hadoop input split must not be null
• Hadoop JobConf must not be null when input split is configur
• Key extractor must not be null.
• Key type must not be null.

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