{"record":{"id":"ecf36746742f67b9","repo":"apache/beam","slug":"pipeline-options-defaultenvironmentconfig-and","errorCode":null,"errorMessage":"Pipeline options defaultEnvironmentConfig and environmentOptions are mutually exclusive.","messagePattern":"Pipeline options defaultEnvironmentConfig and environmentOptions are mutually exclusive\\.","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":621,"sourceCode":"    String assignments =\n        PortablePipelineOptions.getEnvironmentOption(options, processVariablesOption);\n    for (String assignment : assignments.split(\",\", -1)) {\n      String[] tokens = assignment.split(\"=\", -1);\n      if (tokens.length == 1) {\n        throw new IllegalArgumentException(\n            String.format(\"Process environment variable '%s' is not assigned a value.\", tokens[0]));\n      }\n      variables.put(tokens[0], tokens[1]);\n    }\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":603,"sourceCodeEnd":638,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java#L603-L638","documentation":"verifyEnvironmentOptions rejects pipelines that set both defaultEnvironmentConfig and environmentOptions, since they are two overlapping ways to describe the environment. It throws IllegalArgumentException before any environment is created.","triggerScenarios":"Calling PortablePipelineOptions with both setDefaultEnvironmentConfig(...) and a non-empty setEnvironmentOptions(...) — commonly when legacy config from an old job is combined with new environment options.","commonSituations":"Migrating from defaultEnvironmentConfig (old style) to environmentOptions (new style) and leaving both; templated pipeline options merging defaults from different sources.","solutions":["Remove one of the two options — keep environmentOptions (and delete defaultEnvironmentConfig) or vice versa","If migrating, port the values in defaultEnvironmentConfig into the equivalent environmentOptions entries","Audit pipeline option templates/defaults so only one source is ever populated"],"exampleFix":"// before\noptions.setDefaultEnvironmentConfig(\"{\\\"command\\\":\\\"java -jar h.jar\\\"}\");\noptions.setEnvironmentOptions(new String[]{\"process_command=java -jar h.jar\"});\n// after\noptions.setEnvironmentOptions(new String[]{\"process_command=java -jar h.jar\"});","handlingStrategy":"validation","validationCode":"if (options.getEnvironmentOptions() != null && !options.getEnvironmentOptions().isEmpty()\n    && options.getDefaultEnvironmentConfig() != null) {\n  throw new IllegalArgumentException(\"set only one of defaultEnvironmentConfig / environmentOptions\");\n}","typeGuard":null,"tryCatchPattern":"try { env = Environments.createOrGetDefaultEnvironment(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"mutually exclusive\")) { /* drop one option and retry */ } }","preventionTips":["Standardize on environmentOptions in new code","Clean legacy defaultEnvironmentConfig from templates","Add a pre-submit options sanity check"],"tags":["java","apache-beam","environment","conflicting-options"],"backgroundTag":"mutually-exclusive-options","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"}