apache/flink · error · IllegalArgumentException

The broadcast input root operator may not be null.

Error message

The broadcast input root operator may not be null.

What it means

Thrown by AbstractUdfOperator.setBroadcastVariable(String name, Operator<?> root) when the root operator argument is null. The root defines the data-producing sub-plan for the broadcast variable; a null root would leave the broadcast input dangling with no data source, so the API rejects it immediately.

Source

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

     *
     * @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 source operator is created and non-null before calling setBroadcastVariable().
2. Trace the null: if the root comes from a getFirstInput()/getSecondInput() or plan traversal, check why that upstream operator is unset.
3. Use the high-level withBroadcastSet(DataSet, name) API which guarantees a non-null data source.

Example fix

// before
Operator<?> root = maybeNullLookup();
op.setBroadcastVariable("bc", root);
// after
Operator<?> root = maybeNullLookup();
if (root == null) {
    throw new IllegalStateException("Broadcast source for 'bc' was not created");
}
op.setBroadcastVariable("bc", root);

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

When it happens

Trigger: Calling setBroadcastVariable("myName", null) directly, or passing an operator that was retrieved from a collection or plan traversal that returned null (e.g., an unconnected input port or an optional plan element that was never set).

Common situations: Internal plan construction code that wires broadcast variables programmatically where the source operator has not yet been created. In the high-level API this is guarded earlier (withBroadcastSet requires a non-null DataSet), so this is mainly seen in low-level or test code.

Related errors

• The broadcast input name 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/b66e62ebbc88c341. Report an issue: GitHub.