apache/beam · error · IllegalArgumentException

Error constructing default value for gcpTempLocation: tempLo

Error message

Error constructing default value for gcpTempLocation: tempLocation is not a valid GCS path, ${tempLocation}.

What it means

GcpOptions.GcsTempLocationFactory validates the derived tempLocation with the GCS PathValidator; if validation throws, it is rethrown as IllegalArgumentException saying tempLocation is not a valid GCS path. It means the resolved default temp location is not a usable gs:// output prefix.

Source

Thrown at sdks/java/extensions/google-cloud-platform-core/src/main/java/org/apache/beam/sdk/extensions/gcp/options/GcpOptions.java:389

    static final String DEFAULT_REGION = "us-central1";
    private static final Logger LOG = LoggerFactory.getLogger(GcpTempLocationFactory.class);

    @Override
    public @Nullable String create(PipelineOptions options) {
      String tempLocation = options.getTempLocation();
      if (isNullOrEmpty(tempLocation)) {
        tempLocation =
            tryCreateDefaultBucket(
                options,
                newCloudResourceManagerClient(options.as(CloudResourceManagerOptions.class))
                    .build());
        options.setTempLocation(tempLocation);
      } else {
        try {
          PathValidator validator = options.as(GcsOptions.class).getPathValidator();
          validator.validateOutputFilePrefixSupported(tempLocation);
        } catch (Exception e) {
          throw new IllegalArgumentException(
              String.format(
                  "Error constructing default value for gcpTempLocation: tempLocation is not"
                      + " a valid GCS path, %s. ",
                  tempLocation),
              e);
        }
      }

      if (isSoftDeletePolicyEnabled(options, tempLocation)) {
        LOG.warn(
            "The bucket of gcpTempLocation {} has soft delete policy enabled."
                + " Dataflow jobs use Cloud Storage to store temporary files during pipeline"
                + " execution. To avoid being billed for unnecessary storage costs, turn off the soft"
                + " delete feature on buckets that your Dataflow jobs use for temporary storage."
                + " For more information, see"
                + " https://cloud.google.com/storage/docs/use-soft-delete#remove-soft-delete-policy.",
            tempLocation);
      }

View on GitHub (pinned to 12126d8942)

Solutions

Explicitly set --gcpTempLocation (or --tempLocation) to a valid gs://bucket/path prefix
Create the bucket and confirm it is in the same project as --project
Grant the identity storage.objects.create/list on the bucket
Check that no conflicting --tempLocation default factory is producing a non-GCS path

Example fix

// before
--tempLocation=/tmp/beam-temp
// after
--tempLocation=gs://my-bucket/temp

Defensive patterns

Strategy: validation

Validate before calling

String tmp = options.as(GcpOptions.class).getGcpTempLocation();
if (tmp == null) tmp = options.getTempLocation();
if (tmp == null || !tmp.startsWith("gs://"))
  throw new IllegalArgumentException("tempLocation must be a gs:// path for GCP runs: " + tmp);

Try / catch

try {
  options.as(GcpOptions.class).getGcpTempLocation();
} catch (IllegalArgumentException e) {
  options.as(GcpOptions.class).setGcpTempLocation("gs://my-bucket/temp");
}

Prevention

Always set --gcpTempLocation explicitly for Dataflow runs
Never point tempLocation at a local filesystem path on GCP runners
Pre-create the bucket and confirm write access
Keep tempLocation and project in the same GCP project

When it happens

Trigger: PipelineOptions validation when gcpTempLocation is unset and tempLocation defaults from project/bucket inference, then validator.validateOutputFilePrefixSupported(tempLocation) throws because the string is not gs:// prefixed, the bucket is missing, or is not writable.

Common situations: Setting tempLocation to a local directory (e.g. /tmp) instead of a GCS path when running on Dataflow; typo in bucket name; bucket in a different project; no storage.objects.create permission.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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