What causes "Failed to parse secret option" in apache/beam?

Inspect the cause chain (getCause()) to find the real failure raised by the secret factory.

apache/beam · error · RuntimeException

Failed to parse secret option

Error message

Failed to parse secret option

What it means

Wraps any non-IllegalArgumentException/NullPointerException failure raised while creating the Secret from the parsed parameters into a RuntimeException with message 'Failed to parse secret option'. It preserves the original cause, e.g. a factory throwing a checked/runtime error while resolving or validating secret parameters.

Source

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

    String secretType = rawType.toLowerCase();
    SecretRegistrar.SecretFactory factory = SECRET_FACTORIES.get(secretType);
    if (factory == null) {
      throw new IllegalArgumentException(
          String.format(
              "Invalid secret type %s, currently supported types: %s", rawType, SUPPORTED_TYPES));
    }

    try {
      return factory.createSecret(paramMap);
    } catch (Exception e) {
      if (e instanceof IllegalArgumentException) {
        throw (IllegalArgumentException) e;
      }
      if (e instanceof NullPointerException) {
        throw (NullPointerException) e;
      }
      throw new RuntimeException("Failed to parse secret option", e);
    }
  }

  /**
   * Return a Secret instance based on secret_manager provider and secret specification JSON string.
   *
   * @param spec Secret string (raw secret or JSON specification string).
   * @param secretManager Secret manager string (e.g. 'GoogleCloudSecretManager').
   * @return An instance of Secret.
   */
  public static Secret fromJson(@Nullable String spec, @Nullable String secretManager) {
    String smManager = secretManager != null ? secretManager.trim() : null;
    if (smManager != null && smManager.isEmpty()) {
      smManager = null;
    }

    Map<String, String> specMap = null;
    if (spec != null && !spec.isEmpty()) {

View on GitHub (pinned to 12126d8942)

Solutions

Inspect the cause chain (getCause()) to find the real failure raised by the secret factory.
Verify every parameter in the option string is expected by the chosen secret type (extra/misspelled params can break factories).
Catch RuntimeException around parseSecretOption at pipeline startup and fail with a clear configuration error message.

Example fix

// before
Secret s = Secret.parseSecretOption(opt); // opaque RuntimeException
// after
try {
  Secret s = Secret.parseSecretOption(opt);
} catch (RuntimeException e) {
  LOG.error("Bad secret option {}: {}", opt, e.getCause(), e);
  throw e;
}

Defensive patterns

Strategy: try-catch

Try / catch

try { Secret s = Secret.parseSecretOption(opt); } catch (RuntimeException e) { Throwable cause = e.getCause(); LOG.error("secret option '{}' failed: {}", opt, cause, e); throw new ConfigurationException("bad secret option", e); }

Prevention

Match parameters to what the chosen secret type's factory expects.
Read the cause chain — the real error is wrapped.
Test secret option parsing at pipeline startup with real config values.

When it happens

Trigger: Calling parseSecretOption with a syntactically valid option whose type-specific factory (e.g. GcpSecret.createSecret) throws an unexpected exception while processing the remaining parameters.

Common situations: Malformed parameter values for a valid type (e.g. bad project/version formats), a factory bug, or unexpected runtime failures inside the secret manager implementation.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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

Related errors

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