apache/flink · error · MutatedConfigurationException

Not allowed configuration change(s) were detected:\n - {erro

Error message

Not allowed configuration change(s) were detected:\n - {errorMessages}

What it means

Thrown by checkNotAllowedConfigurations when the program (user code) has mutated cluster-level configuration options that are not in the allowed wildcard list. This protects against user jobs silently changing cluster-critical settings. The MutatedConfigurationException carries a collection of error messages listing each disallowed change.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/StreamContextEnvironment.java:340

                            applicationId,
                            userJarInfo,
                            allRecoveredJobInfos);
                };
        initializeContextEnvironment(factory);
    }

    public static void unsetAsContext() {
        resetContextEnvironment();
    }

    // --------------------------------------------------------------------------------------------
    // Program Configuration Validation
    // --------------------------------------------------------------------------------------------

    private void checkNotAllowedConfigurations() throws MutatedConfigurationException {
        final Collection<String> errorMessages = collectNotAllowedConfigurations();
        if (!errorMessages.isEmpty()) {
            throw new MutatedConfigurationException(errorMessages);
        }
    }

    /**
     * Collects programmatic configuration changes.
     *
     * <p>For supporting wildcards, the first can be accomplished by simply removing keys, the
     * latter by setting equal fields before comparison.
     */
    private Collection<String> collectNotAllowedConfigurations() {
        if (programConfigEnabled) {
            return Collections.emptyList();
        }

        final List<String> errors = new ArrayList<>();

        final Configuration clusterConfigMap = new Configuration(clusterConfiguration);

View on GitHub (pinned to 2f3c205e92)

Solutions

Set DeploymentOptions.PROGRAM_CONFIG_ENABLED=true if programmatic config changes should be allowed.
Add the specific config key prefix to DeploymentOptions.PROGRAM_CONFIG_WILDCARDS to whitelist it.
Remove the programmatic configuration change from user code and set it at the cluster/deployment level instead.
Review the error message (it lists each disallowed key) and reconcile each one.

Example fix

// before: user code changes a locked config
env.getConfig().setString("execution.checkpointing.interval", "30s");
// throws MutatedConfigurationException

// after: allow programmatic config changes in deployment config
config.set(DeploymentOptions.PROGRAM_CONFIG_ENABLED, true);
// or whitelist the specific key
config.set(DeploymentOptions.PROGRAM_CONFIG_WILDCARDS,
    Collections.singletonList("execution.checkpointing.interval"));

Defensive patterns

Strategy: validation

Validate before calling

// check before executeAsync whether programmatic config changes are allowed
if (!clusterConfig.get(DeploymentOptions.PROGRAM_CONFIG_ENABLED)) {
    // diff user config vs cluster config and verify each changed key
    // is covered by PROGRAM_CONFIG_WILDCARDS
}

Try / catch

try {
    env.executeAsync(streamGraph);
} catch (MutatedConfigurationException e) {
    // e carries a Collection<String> of disallowed config changes
    // reconcile each key or enable program config
    for (String msg : e.getErrorMessages()) {
        LOG.warn("Disallowed config change: {}", msg);
    }
    throw e;
}

Prevention

Set cluster-level configuration options at deployment time, not in user code.
If programmatic config is needed, set PROGRAM_CONFIG_ENABLED=true or add keys to PROGRAM_CONFIG_WILDCARDS.
Document which config keys are safe to override in user jobs.

When it happens

Trigger: User job code modifies Configuration options that differ from the cluster-provided configuration, and programConfigEnabled is false (or the changed key is not covered by programConfigWildcards). The comparison happens at executeAsync time before job submission.

Common situations: User code calls streamExecEnv.getConfig().disableSysoutLogging() or sets a config option that conflicts with cluster policy, or the deployment enforces a locked configuration and the job tries to override checkpointing, parallelism, or state backend settings.

Related errors

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