apache/beam · error · java.lang.RuntimeException

Unable to parse process environment config

Error message

Unable to parse process environment config: %s

What it means

When the default environment type is PROCESS and defaultEnvironmentConfig holds a JSON payload describing the process environment, a failure to parse that JSON (IOException) is rethrown as a RuntimeException naming the config string. The config must be valid JSON with fields like os, arch, command, env.

Solutions

1. Validate that defaultEnvironmentConfig is well-formed JSON matching the process payload schema ({"command": ..., "os": ..., "arch": ..., "env": {...}})
2. Prefer environmentOptions (e.g. process_command=...) instead of defaultEnvironmentConfig for process environments
3. Print and lint the config JSON before submitting the pipeline

Example fix

// before
options.setDefaultEnvironmentConfig("java -jar harness.jar");
// after
options.setDefaultEnvironmentConfig("{\"command\":\"java -jar harness.jar\"}");

String cfg = options.getDefaultEnvironmentConfig();
if (cfg != null) { new ObjectMapper().readTree(cfg); // throws if malformed
  if (!cfg.trim().startsWith("{")) throw new IllegalArgumentException("config must be a JSON object"); }

try { env = Environments.createOrGetDefaultEnvironment(options); } catch (RuntimeException e) { if (e.getMessage().startsWith("Unable to parse process environment config")) { /* fix the JSON config */ } }

When it happens

Trigger: Setting PortablePipelineOptions.setDefaultEnvironmentConfig to malformed JSON, or JSON whose shape does not match the ProcessPayload proto (so Jackson/PB parsing throws IOException).

Common situations: Hand-editing the environment config JSON and introducing syntax errors; passing a command string instead of JSON; quoting/shell-escaping issues when setting the option via CLI.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• A function must be provided to convert the input type into…
• A PValue contained in
• A schema was provided without a data format (or viceversa)…
• All inherited interfaces of
• An unsupported type of cache was passed in. Received

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

Appendix: source

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

      if (processCommand.isEmpty()) {
        throw new IllegalArgumentException(
            String.format(
                "Environment option '%s' must be set for process environment.",
                processCommandOption));
      }
      return createProcessEnvironment("", "", processCommand, getProcessVariables(options));
    }
    try {
      ProcessPayloadReferenceJSON payloadReferenceJSON =
          MAPPER.readValue(
              options.getDefaultEnvironmentConfig(), ProcessPayloadReferenceJSON.class);
      return createProcessEnvironment(
          payloadReferenceJSON.getOs(),
          payloadReferenceJSON.getArch(),
          payloadReferenceJSON.getCommand(),
          payloadReferenceJSON.getEnv());
    } catch (IOException e) {
      throw new RuntimeException(
          String.format(
              "Unable to parse process environment config: %s",
              options.getDefaultEnvironmentConfig()),
          e);
    }
  }

  public static Environment createProcessEnvironment(
      String os, String arch, String command, Map<String, String> env) {
    ProcessPayload.Builder builder = ProcessPayload.newBuilder();
    if (!Strings.isNullOrEmpty(os)) {
      builder.setOs(os);
    }
    if (!Strings.isNullOrEmpty(arch)) {
      builder.setArch(arch);
    }
    if (!Strings.isNullOrEmpty(command)) {
      builder.setCommand(command);

View on GitHub (pinned to 12126d8942)