{"record":{"id":"206d07ba3fdcfa99","repo":"apache/beam","slug":"environment-option-s-is-incompatible-with-environment-type-s","errorCode":null,"errorMessage":"Environment option '%s' is incompatible with environment type '%s'.","messagePattern":"Environment option '(.+?)' is incompatible with environment type '(.+?)'\\.","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java","lineNumber":630,"sourceCode":"    }\n    return variables.build();\n  }\n\n  private static void verifyEnvironmentOptions(PortablePipelineOptions options) {\n    if (options.getEnvironmentOptions() == null || options.getEnvironmentOptions().isEmpty()) {\n      return;\n    }\n    if (!Strings.isNullOrEmpty(options.getDefaultEnvironmentConfig())) {\n      throw new IllegalArgumentException(\n          \"Pipeline options defaultEnvironmentConfig and environmentOptions are mutually exclusive.\");\n    }\n    Set<String> allowedOptions =\n        allowedEnvironmentOptions.getOrDefault(\n            options.getDefaultEnvironmentType(), ImmutableSet.of());\n    for (String option : options.getEnvironmentOptions()) {\n      String optionName = option.split(\"=\", -1)[0];\n      if (!allowedOptions.contains(optionName)) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"Environment option '%s' is incompatible with environment type '%s'.\",\n                option, options.getDefaultEnvironmentType()));\n      }\n    }\n  }\n}\n","sourceCodeStart":612,"sourceCodeEnd":638,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java#L612-L638","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\noptions.setDefaultEnvironmentType(\"PROCESS\");\noptions.setEnvironmentOptions(new String[]{\"docker_container_image=apache/beam_java11_sdk:2.50.0\"});\n// after\noptions.setDefaultEnvironmentType(\"DOCKER\");\noptions.setEnvironmentOptions(new String[]{\"docker_container_image=apache/beam_java11_sdk:2.50.0\"});","handlingStrategy":"validation","validationCode":"for (String opt : options.getEnvironmentOptions()) {\n  String name = opt.split(\"=\", -1)[0];\n  // ensure name is in the allowed set for options.getDefaultEnvironmentType()\n}","typeGuard":null,"tryCatchPattern":"try { env = Environments.createOrGetDefaultEnvironment(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"is incompatible with environment type\")) { /* fix or move the option */ } }","preventionTips":["Match options to the configured environment type","Watch for typos — unknown keys are rejected, not ignored","Update all options when switching environment types"],"tags":["java","apache-beam","environment","invalid-option"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}