apache/beam · error · IllegalArgumentException

Secret string must contain a valid type parameter

Error message

Secret string must contain a valid type parameter

What it means

parseSecretOption requires the option string to contain a 'type' parameter identifying which secret manager to use. If the parsed parameter map has no 'type' key, the option string is malformed and IllegalArgumentException is thrown.

Source

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

   * '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");
    }

    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) {

View on GitHub (pinned to 12126d8942)

Solutions

Include the type parameter first in the option string, e.g. 'type:GcpSecret;version_name=my_secret/versions/latest'.
Check for typos such as 'Type:' or 'secret_type:' — the key must be exactly lowercase 'type'.
Validate the option string in your pipeline setup code before calling parseSecretOption.

Example fix

// before
Secret s = Secret.parseSecretOption("version_name:my_secret/versions/latest");
// after
Secret s = Secret.parseSecretOption("type:GcpSecret;version_name:my_secret/versions/latest");

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = secretOption != null && secretOption.matches(".*(^|;)type:[^;]+.*");
if (!ok) { throw new IllegalArgumentException("secret option must start with 'type:<manager>;..."); }

Try / catch

try { Secret s = Secret.parseSecretOption(opt); } catch (IllegalArgumentException e) { LOG.error("malformed secret option: {}", opt, e); throw e; }

Prevention

Always begin the option string with 'type:<SecretManager>'.
Keep an option-string constant/template in code instead of ad-hoc strings.
Lint config templates to ensure placeholders are substituted.

When it happens

Trigger: Calling Secret.parseSecretOption with a string lacking 'type:', e.g. "version_name=my_secret/versions/latest" or an empty/blank string that yields an empty parameter map.

Common situations: Typos in the option string (missing the type: prefix), copying only the version_name portion from documentation, or passing an empty string from an unset-but-not-null config value.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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