{"record":{"id":"13bdbd46605b4a07","repo":"apache/beam","slug":"environment-option-s-must-be-set-for-process-environment","errorCode":null,"errorMessage":"Environment option '%s' must be set for process environment.","messagePattern":"Environment option '(.+?)' must be set for process environment\\.","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":261,"sourceCode":"    return Environment.newBuilder()\n        .setUrn(BeamUrns.getUrn(StandardEnvironments.Environments.EXTERNAL))\n        .setPayload(payloadBuilder.build().toByteString())\n        .build();\n  }\n\n  private static Environment createEmbeddedEnvironment(String config) {\n    return Environment.newBuilder()\n        .setUrn(ENVIRONMENT_EMBEDDED)\n        .setPayload(ByteString.copyFromUtf8(MoreObjects.firstNonNull(config, \"\")))\n        .build();\n  }\n\n  private static Environment createProcessEnvironment(PortablePipelineOptions options) {\n    if (options.getEnvironmentOptions() != null) {\n      String processCommand =\n          PortablePipelineOptions.getEnvironmentOption(options, processCommandOption);\n      if (processCommand.isEmpty()) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"Environment option '%s' must be set for process environment.\",\n                processCommandOption));\n      }\n      return createProcessEnvironment(\"\", \"\", processCommand, getProcessVariables(options));\n    }\n    try {\n      ProcessPayloadReferenceJSON payloadReferenceJSON =\n          MAPPER.readValue(\n              options.getDefaultEnvironmentConfig(), ProcessPayloadReferenceJSON.class);\n      return createProcessEnvironment(\n          payloadReferenceJSON.getOs(),\n          payloadReferenceJSON.getArch(),\n          payloadReferenceJSON.getCommand(),\n          payloadReferenceJSON.getEnv());\n    } catch (IOException e) {\n      throw new RuntimeException(\n          String.format(","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java#L243-L279","documentation":"createProcessEnvironment builds a process-based SDK environment, which requires the process command environment option. When the environmentOptions do not contain the required '--environmentOption=process_command=...' (option value empty), it throws IllegalArgumentException naming the missing option key.","triggerScenarios":"Setting defaultEnvironmentType to PROCESS (external/process) and providing environmentOptions without the process_command option, or providing it with an empty value.","commonSituations":"Configuring a custom SDK harness launched as a local process; copying environment option lists between environment types and dropping the process command; typos in the option key.","solutions":["Add the option process_command=... to PortablePipelineOptions.setEnvironmentOptions, e.g. \"process_command=java ... org.apache.beam.sdk.harness.JvmInitializer\"","Verify the option key spelling matches the processCommandOption constant (process_command)","Alternatively use a Docker environment type if you do not need a raw process command"],"exampleFix":"// before\noptions.setEnvironmentType(\"PROCESS\");\noptions.setEnvironmentOptions(new String[]{});\n// after\noptions.setEnvironmentType(\"PROCESS\");\noptions.setEnvironmentOptions(new String[]{\"process_command=java -jar beam-sdks-java-harness.jar\"});","handlingStrategy":"validation","validationCode":"boolean hasCommand = options.getEnvironmentOptions() != null\n    && Arrays.stream(options.getEnvironmentOptions())\n        .anyMatch(o -> o.startsWith(\"process_command=\"));\nif (\"PROCESS\".equals(options.getDefaultEnvironmentType()) && !hasCommand) {\n  throw new IllegalArgumentException(\"process_command required for PROCESS environment\");\n}","typeGuard":null,"tryCatchPattern":"try { env = Environments.createOrGetDefaultEnvironment(options); } catch (IllegalArgumentException e) { /* supply process_command option and retry */ }","preventionTips":["Always pair PROCESS environment type with a process_command option","Verify option keys against Beam's documented constants","Test environment creation in a unit test before submitting jobs"],"tags":["java","apache-beam","environment","process-environment"],"backgroundTag":"missing-env-var","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"}