apache/beam · error · IllegalArgumentException

Secret name must be specified in secret spec.

Error message

Secret name must be specified in secret spec.

What it means

GcpSecret.parseVersionName builds a SecretVersionName from the spec. If no version_name is given and the 'name' key is missing or empty, it throws IllegalArgumentException 'Secret name must be specified in secret spec.' — a spec must identify either a full version name or a secret name to resolve.

Source

Thrown at sdks/java/extensions/google-cloud-platform-core/src/main/java/org/apache/beam/sdk/extensions/gcp/util/GcpSecret.java:82

      List<String> sortedInvalid = new ArrayList<>(invalidKeys);
      Collections.sort(sortedInvalid);
      throw new IllegalArgumentException(
          "Invalid secret parameter " + String.join(", ", sortedInvalid));
    }
    String versionName = parseVersionName(specMap);
    return new GcpSecret(versionName);
  }

  /** Parses the version name from a specification dictionary. */
  private static String parseVersionName(Map<String, String> specMap) {
    String versionNameParam = specMap.get("version_name");
    if (!Strings.isNullOrEmpty(versionNameParam)) {
      return Preconditions.checkNotNull(
          versionNameParam, "version_name must contain a valid value for versionName parameter");
    }
    String secretId = specMap.get("name");
    if (Strings.isNullOrEmpty(secretId)) {
      throw new IllegalArgumentException("Secret name must be specified in secret spec.");
    }
    String projectId = resolveGcpProjectId(specMap.get("project"), "secret '" + secretId + "'");
    String versionId = specMap.getOrDefault("version", "latest");
    if (Strings.isNullOrEmpty(versionId)) {
      versionId = "latest";
    }
    return String.format("projects/%s/secrets/%s/versions/%s", projectId, secretId, versionId);
  }

  /**
   * Resolves the GCP project ID from the provided value, environment variables, or Application
   * Default Credentials.
   */
  static String resolveGcpProjectId(@Nullable String projectId, @Nullable String context) {
    if (!Strings.isNullOrEmpty(projectId)) {
      return Preconditions.checkNotNull(projectId);
    }
    String envProject = System.getenv("GOOGLE_CLOUD_PROJECT");

View on GitHub (pinned to 12126d8942)

Solutions

1. Add "name": "<secret-id>" to the spec
2. Or provide "version_name": "projects/P/secrets/S/versions/V" instead
3. Check the templating/config source that produced an empty name

Example fix

// before
Map<String,String> spec = Map.of("project","p");
// after
Map<String,String> spec = Map.of("project","p","name","my-secret");

if (!spec.containsKey("version_name") && Strings.isNullOrEmpty(spec.get("name"))) {
  throw new IllegalArgumentException("secret spec needs either version_name or name");
}

try { GcpSecret.fromMap(spec); } catch (IllegalArgumentException e) { fail("Secret spec incomplete: " + e.getMessage()); }

When it happens

Trigger: Calling GcpSecret.fromMap with an empty map, a spec with only 'project'/'version', or a spec whose 'name' value is empty string.

Common situations: Templated/config-driven specs where the name substitution failed and resolved to empty; hand-written specs omitting 'name'.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid secret parameter %s
• Failed to retrieve or create secret bytes
• Invalid secret parameter %s
• Failed to retrieve secret bytes
• Provided Secret must be in the form projects/{project}/secre

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