apache/beam · error · ConfigurationException

GCP Authentication Extension not configured properly: %s not

Error message

GCP Authentication Extension not configured properly: %s not configured. Configure it by exporting environment variable %s or system property %s

What it means

ConfigurableOption.getConfiguredValue() in the OpenTelemetry GCP auth extension requires the option's system property to be set (via config properties). If the property lookup returns null or an empty string, it throws ConfigurationException telling the user to export the corresponding environment variable or set the system property. The extension cannot authenticate to GCP without this value.

Source

Thrown at sdks/java/extensions/opentelemetry-gcp-auth-extension/src/main/java/org/apache/beam/sdk/extensions/opentelemetry/gcp/auth/ConfigurableOption.java:123

   */
  String getUserReadableName() {
    return this.userReadableName;
  }

  /**
   * Retrieves the configured value for this option. This method checks the environment variable
   * first and then the system property.
   *
   * @return The configured value as a string, or throws an exception if not configured.
   * @throws ConfigurationException if neither the environment variable nor the system property is
   *     set.
   */
  String getConfiguredValue(ConfigProperties configProperties) {
    String configuredValue = configProperties.getString(this.getSystemProperty());
    if (configuredValue != null && !configuredValue.isEmpty()) {
      return configuredValue;
    } else {
      throw new ConfigurationException(
          String.format(
              "GCP Authentication Extension not configured properly: %s not configured. Configure it by exporting environment variable %s or system property %s",
              this.userReadableName, this.getEnvironmentVariable(), this.getSystemProperty()));
    }
  }

  /**
   * Retrieves the value for this option, prioritizing environment variables and system properties.
   * If neither an environment variable nor a system property is set for this option, the provided
   * fallback function is used to determine the value.
   *
   * @param fallback A {@link Supplier} that provides the default value for the option when it is
   *     not explicitly configured via an environment variable or system property.
   * @return The configured value for the option, obtained from the environment variable, system
   *     property, or the fallback function, in that order of precedence.
   */
  String getConfiguredValueWithFallback(
      ConfigProperties configProperties, Supplier<String> fallback) {

View on GitHub (pinned to 12126d8942)

Solutions

Export the named environment variable before launching the pipeline (e.g. export GOOGLE_CLOUD_PROJECT=my-project).
Alternatively pass the system property with -D<property>=<value> in the JVM args.
Check for empty-string values: unset and re-export the variable with a real value.
Verify the variable is visible to the actual process (container env, k8s pod spec, CI job env).

Example fix

// before (no env set)
java -jar pipeline.jar
// after
export GOOGLE_CLOUD_PROJECT=my-project
java -Dgoogle.cloud.project=my-project -jar pipeline.jar

Defensive patterns

Strategy: try-catch

Validate before calling

String required = System.getenv("GOOGLE_CLOUD_PROJECT");
if (required == null || required.isEmpty()) {
  throw new IllegalStateException("GOOGLE_CLOUD_PROJECT must be set before running the pipeline");
}

Try / catch

try {
  String value = option.getConfiguredValue(configProperties);
} catch (org.apache.beam.sdk.extensions.opentelemetry.gcp.auth.ConfigurationException e) {
  logger.error("Missing GCP auth config: {}", e.getMessage());
  throw new IllegalStateException("Set the required env var or system property and retry", e);
}

Prevention

Set required GCP env vars in the deployment manifest (Dockerfile, k8s pod spec, CI env), not just your shell.
Prefer explicit -D system properties when launching pipeline JVMs.
Fail fast with an env check at application startup.
Watch for empty-string exports which trigger the same error.

When it happens

Trigger: Running a Beam pipeline with the GCP auth extension where neither the environment variable nor the system property for a required option (e.g. project ID, quota project) is set; the property is present but is an empty string.

Common situations: Deploying to a container/CI environment where the developer's local GCP env vars aren't exported, forgetting to set GOOGLE_CLOUD_PROJECT or the quota-project property, or an empty export like GOOGLE_APPLICATION_CREDENTIALS="".

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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