apache/beam · error · IllegalArgumentException

Secret option string cannot be null

Error message

Secret option string cannot be null

What it means

parseSecretOption validates its input before parsing the 'type:key;key=value' style secret option string. Passing null immediately throws IllegalArgumentException because a null option cannot identify any secret. This is a fail-fast guard against misconfigured pipeline options.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/Secret.java:206

  }

  /** Returns secret value as UTF-8 string without caching. */
  public @Nullable String getString() {
    return getString(false);
  }

  /**
   * Parses a secret string and returns the appropriate secret type.
   *
   * <p>The secret string should be formatted like:
   * 'type:&lt;secret_type&gt;;&lt;secret_param&gt;:&lt;value&gt;'
   *
   * <p>For example, 'type:GcpSecret;version_name:my_secret/versions/latest' would return a
   * GcpSecret initialized with 'my_secret/versions/latest'.
   */
  public static Secret parseSecretOption(String secretOption) {
    if (secretOption == null) {
      throw new IllegalArgumentException("Secret option string cannot be null");
    }
    Map<String, String> paramMap = new HashMap<>();
    for (String param : secretOption.split(";", -1)) {
      String[] parts = param.split(":", 2);
      if (parts.length == 2) {
        paramMap.put(parts[0], parts[1]);
      }
    }

    if (!paramMap.containsKey("type")) {
      throw new IllegalArgumentException("Secret string must contain a valid type parameter");
    }

    String rawType = paramMap.remove("type");
    if (rawType == null || rawType.isEmpty()) {
      throw new IllegalArgumentException("Secret string must contain a valid type parameter");
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Set the secret option in your pipeline launch configuration (e.g. --secretOption=type:GcpSecret;version_name=my_secret/versions/latest).
2. Null-check the option before calling parseSecretOption and skip or fail with a clearer message.
3. Give the pipeline option a sensible default or make it @Required so the job fails earlier with a validation error.

Example fix

// before
Secret secret = Secret.parseSecretOption(options.getSecretOption());
// after
String opt = options.getSecretOption();
Secret secret = opt == null ? null : Secret.parseSecretOption(opt);

if (secretOption == null) { throw new IllegalStateException("--secretOption must be set"); }

if (secretOption != null) { Secret s = Secret.parseSecretOption(secretOption); }

try { Secret s = Secret.parseSecretOption(opt); } catch (IllegalArgumentException e) { /* handle null/malformed option */ }

When it happens

Trigger: Calling Secret.parseSecretOption(null), typically when a pipeline option holding the secret specification was never set.

Common situations: A pipeline option like --secretOption is left unset (null default) while the code unconditionally parses it; wiring code passes an unset ValueProvider or null config field into parseSecretOption.

Related errors

• Secret string must contain a valid type parameter
• Invalid secret type %s, currently supported types: %s
• Failed to parse secret option
• Unrecognized value for stable unique names:
• Unsupported secret manager: '%s'. Currently supported option

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