apache/beam · error · IOException

Unable to get the file object for path %s.

Error message

Unable to get the file object for path %s.

What it means

GcsUtilV1.getObject wraps failures from the GCS Storage.objects.get call into this IOException after retries are exhausted. The library throws it when a GCS object cannot be fetched for the given gs:// path; a genuine 404 is converted to FileNotFoundException first, so this error indicates a non-404 failure (or an interrupted call). The original exception is chained as the cause.

Source

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

  public StorageObject getObject(GcsPath gcsPath) throws IOException {
    return getObject(gcsPath, createBackOff(), Sleeper.DEFAULT);
  }

  @VisibleForTesting
  StorageObject getObject(GcsPath gcsPath, BackOff backoff, Sleeper sleeper) throws IOException {
    Storage.Objects.Get getObject =
        storageClient.objects().get(gcsPath.getBucket(), gcsPath.getObject());
    try {
      return ResilientOperation.retry(
          getObject::execute, backoff, RetryDeterminer.SOCKET_ERRORS, IOException.class, sleeper);
    } catch (IOException | InterruptedException e) {
      if (e instanceof InterruptedException) {
        Thread.currentThread().interrupt();
      }
      if (e instanceof IOException && errorExtractor.itemNotFound((IOException) e)) {
        throw new FileNotFoundException(gcsPath.toString());
      }
      throw new IOException(
          String.format("Unable to get the file object for path %s.", gcsPath), e);
    }
  }

  /**
   * Returns {@link StorageObjectOrIOException StorageObjectOrIOExceptions} for the given {@link
   * GcsPath GcsPaths}.
   */
  public List<StorageObjectOrIOException> getObjects(List<GcsPath> gcsPaths) throws IOException {
    if (gcsPaths.isEmpty()) {
      return ImmutableList.of();
    } else if (gcsPaths.size() == 1) {
      GcsPath path = gcsPaths.get(0);
      try {
        StorageObject object = getObject(path);
        return ImmutableList.of(StorageObjectOrIOException.create(object));
      } catch (IOException e) {
        return ImmutableList.of(StorageObjectOrIOException.create(e));

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the chained cause (e.getCause()) to see the real GCS error code and address it
2. Verify the service account has storage.objects.get permission (roles/storage.objectViewer)
3. Confirm the gs:// path and bucket spelling are correct
4. Retry later if the cause is a transient 5xx/socket error; increase backoff if needed

Example fix

// before
StorageObject obj = gcsUtil.getObject(path); // throws IOException with this message
// after
try {
  StorageObject obj = gcsUtil.getObject(path);
} catch (FileNotFoundException e) {
  // object truly missing
} catch (IOException e) {
  LOG.error("getObject failed for {}: {}", path, e.getCause(), e);
  throw e;
}

// pre-check
if (gcsUtil.objectExists(gcsPath)) { /* safe to getObject */ }

boolean isInterruptedFailure(IOException e) { return e.getCause() instanceof InterruptedException; }

try {
  StorageObject obj = gcsUtil.getObject(path);
} catch (FileNotFoundException e) {
  // handle missing object
} catch (IOException e) {
  LOG.error("getObject failed, cause={}", e.getCause(), e);
  throw e;
}

When it happens

Trigger: Calling getObject(path) when the GCS API repeatedly fails with retryable errors (socket errors, 5xx), when the caller is interrupted while backing off, when permissions deny object read (403), or when the bucket/object path is malformed.

Common situations: Missing or insufficient GCS permissions on the object, transient GCS outages exhausting the backoff, a typo in the bucket name that yields 403 rather than 404, or thread interruption during shutdown.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Unable to match files in bucket %s, prefix %s.
• Unable to read file(s) after retrying %d times
• Failed to retrieve secret bytes
• Error executing batch GCS request
• Error completing file copies with retries, sample: from %s t

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