apache/beam · error · java.lang.IllegalArgumentException

Process environment variable

Error message

Process environment variable '%s' is not assigned a value.

What it means

getProcessVariables parses the process_variables environment option, which must be a comma-separated list of KEY=VALUE assignments. An entry without '=' (only one token) throws IllegalArgumentException naming the variable name. Every process variable must have an explicit value.

Solutions

Give every variable a value with '=', even if empty: 'FOO=' not 'FOO'
Check the process_variables option string for missing '=' and stray commas
Quote the option value in your shell/CLI so characters are not mangled

Example fix

// before
--environmentOption=process_variables=LOG_LEVEL,DEBUG=true
// after
--environmentOption=process_variables=LOG_LEVEL=info,DEBUG=true

Defensive patterns

Strategy: validation

Validate before calling

for (String opt : options.getEnvironmentOptions()) {
  if (opt.startsWith("process_variables=")) {
    for (String a : opt.substring("process_variables=".length()).split(",", -1)) {
      if (!a.contains("=")) throw new IllegalArgumentException("variable without '=': " + a);
    }
  }
}

Try / catch

try { env = Environments.createOrGetDefaultEnvironment(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("is not assigned a value")) { /* fix the variables list */ } }

Prevention

Always write KEY=VALUE, using KEY= for empty values
Avoid bare names and stray commas in process_variables
Quote option values in shells

When it happens

Trigger: Setting environmentOptions with an entry like 'process_variables=FOO,BAR=1' where FOO has no '=', or a trailing/empty segment that splits to a single token.

Common situations: Typos omitting '='; assuming empty values can be written as bare keys; shell quoting stripping characters from the option.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

  private static String getDockerContainerImage(PortablePipelineOptions options) {
    String environmentConfig = options.getDefaultEnvironmentConfig();
    String environmentOption =
        PortablePipelineOptions.getEnvironmentOption(options, dockerContainerImageOption);
    if (environmentConfig != null && !environmentConfig.isEmpty()) {
      return environmentConfig;
    }
    return environmentOption;
  }

  private static Map<String, String> getProcessVariables(PortablePipelineOptions options) {
    ImmutableMap.Builder<String, String> variables = ImmutableMap.builder();
    String assignments =
        PortablePipelineOptions.getEnvironmentOption(options, processVariablesOption);
    for (String assignment : assignments.split(",", -1)) {
      String[] tokens = assignment.split("=", -1);
      if (tokens.length == 1) {
        throw new IllegalArgumentException(
            String.format("Process environment variable '%s' is not assigned a value.", tokens[0]));
      }
      variables.put(tokens[0], tokens[1]);
    }
    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());

View on GitHub (pinned to 12126d8942)