apache/flink · warning · UnsupportedOperationException

The configuration is unmodifiable; its contents cannot be ch

Error message

The configuration is unmodifiable; its contents cannot be changed.

What it means

Thrown by UnmodifiableConfiguration.error() whenever any mutating operation (addAll, addAll with prefix, setValueInternal, removeConfig) is called. UnmodifiableConfiguration wraps a Configuration snapshot and intentionally blocks all writes to guarantee immutability.

Source

Thrown at flink-core/src/main/java/org/apache/flink/configuration/UnmodifiableConfiguration.java:73

    @Override
    public final void addAll(Configuration other, String prefix) {
        error();
    }

    @Override
    final <T> void setValueInternal(String key, T value, boolean canBePrefixMap) {
        error();
    }

    @Override
    public <T> boolean removeConfig(ConfigOption<T> configOption) {
        error();
        return false;
    }

    private void error() {
        throw new UnsupportedOperationException(
                "The configuration is unmodifiable; its contents cannot be changed.");
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Create a mutable copy before modifying: Configuration mutable = new Configuration(unmodifiableConfig);
Check isInstanceOf / type before mutating, or design APIs to return mutable copies.
Avoid mutating configs received from external/framework sources.

Example fix

// before
unmodifiableConfig.setString("key", "value"); // throws

// after
Configuration mutable = new Configuration(unmodifiableConfig);
mutable.setString("key", "value");

Defensive patterns

Strategy: type-guard

Validate before calling

Configuration target = (config instanceof UnmodifiableConfiguration)
    ? new Configuration(config)
    : config;
target.setString("key", "value");

Type guard

static boolean isMutable(Configuration c) { return !(c instanceof UnmodifiableConfiguration); }

Try / catch

try {
    config.setString(key, value);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("unmodifiable")) {
        config = new Configuration(config);
        config.setString(key, value);
    }
}

Prevention

Create a mutable copy before modifying configs received from frameworks.
Check for UnmodifiableConfiguration before mutating.
Design APIs to return mutable copies when callers may need to extend.

When it happens

Trigger: Obtaining an UnmodifiableConfiguration (e.g., from certain APIs that return read-only views) and then calling set, setString, addAll, or removeConfig on it. Passing an UnmodifiableConfiguration to code that attempts to modify it.

Common situations: Framework code that receives a Configuration and tries to add defaults, not knowing it's unmodifiable. Libraries that mutate a passed-in config. User code that reads config from a context that returns an UnmodifiableConfiguration.

Related errors

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