apache/beam · error · java.lang.IllegalArgumentException

Environment option ' ' is incompatible with environment…

Error message

Environment option '%s' is incompatible with environment type '%s'.

What it means

verifyEnvironmentOptions validates each entry in environmentOptions against the whitelist of options allowed for the configured defaultEnvironmentType. An option key not in that set throws IllegalArgumentException showing both the option and the environment type. It prevents meaningless or contradictory environment configuration.

Solutions

Move the option to an environment type that allows it (e.g. docker_container_image only with DOCKER type)
Fix the option key spelling to match the allowed set for your defaultEnvironmentType
Remove the incompatible option if it does not apply to your environment

Example fix

// before
options.setDefaultEnvironmentType("PROCESS");
options.setEnvironmentOptions(new String[]{"docker_container_image=apache/beam_java11_sdk:2.50.0"});
// after
options.setDefaultEnvironmentType("DOCKER");
options.setEnvironmentOptions(new String[]{"docker_container_image=apache/beam_java11_sdk:2.50.0"});

Defensive patterns

Strategy: validation

Validate before calling

for (String opt : options.getEnvironmentOptions()) {
  String name = opt.split("=", -1)[0];
  // ensure name is in the allowed set for options.getDefaultEnvironmentType()
}

Try / catch

try { env = Environments.createOrGetDefaultEnvironment(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("is incompatible with environment type")) { /* fix or move the option */ } }

Prevention

Match options to the configured environment type
Watch for typos — unknown keys are rejected, not ignored
Update all options when switching environment types

When it happens

Trigger: Using a Docker-only option (e.g. docker_container_image) with defaultEnvironmentType=PROCESS, or a process option with DOCKER, or any typo in an option name (no allowed set matches the unknown key).

Common situations: Copying environment options between jobs with different environment types; typos like 'processcommand=' instead of 'process_command='; mixing options when switching a pipeline from Docker to process environments.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/206d07ba3fdcfa99. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java:630

    }
    return variables.build();
  }

  private static void verifyEnvironmentOptions(PortablePipelineOptions options) {
    if (options.getEnvironmentOptions() == null || options.getEnvironmentOptions().isEmpty()) {
      return;
    }
    if (!Strings.isNullOrEmpty(options.getDefaultEnvironmentConfig())) {
      throw new IllegalArgumentException(
          "Pipeline options defaultEnvironmentConfig and environmentOptions are mutually exclusive.");
    }
    Set<String> allowedOptions =
        allowedEnvironmentOptions.getOrDefault(
            options.getDefaultEnvironmentType(), ImmutableSet.of());
    for (String option : options.getEnvironmentOptions()) {
      String optionName = option.split("=", -1)[0];
      if (!allowedOptions.contains(optionName)) {
        throw new IllegalArgumentException(
            String.format(
                "Environment option '%s' is incompatible with environment type '%s'.",
                option, options.getDefaultEnvironmentType()));
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)