apache/beam · error · UnsupportedOperationException

Can't resolve the sibling of a root path: %s

Error message

Can't resolve the sibling of a root path: %s

What it means

resolveSibling resolves the given path against this path's parent. A bucket-root GcsPath (only scheme+bucket, getNameCount() < 2) has no resolvable parent context, so the method throws UnsupportedOperationException.

Source

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

    if (object.isEmpty()) {
      return new GcsPath(fs, bucket, other);
    } else if (object.endsWith("/")) {
      return new GcsPath(fs, bucket, object + other);
    } else {
      return new GcsPath(fs, bucket, object + "/" + other);
    }
  }

  @Override
  public Path resolveSibling(Path other) {
    throw new UnsupportedOperationException();
  }

  @Override
  public Path resolveSibling(String other) {
    if (getNameCount() < 2) {
      throw new UnsupportedOperationException("Can't resolve the sibling of a root path: " + this);
    }
    GcsPath parent = getParent();
    return (parent == null) ? fromUri(other) : parent.resolve(other);
  }

  @Override
  public Path relativize(Path other) {
    throw new UnsupportedOperationException();
  }

  @Override
  public GcsPath toAbsolutePath() {
    return this;
  }

  @Override
  public GcsPath toRealPath(LinkOption... options) throws IOException {
    return this;

View on GitHub (pinned to 12126d8942)

Solutions

1. Guard with getNameCount() >= 2 before calling resolveSibling
2. Resolve against the desired bucket explicitly: GcsPath.fromUri("gs://bucket/").resolve(other)
3. Rework the algorithm to build target paths from the bucket root instead of siblings

Example fix

// before
Path sibling = gcsPath.resolveSibling(other);
// after
Path sibling = gcsPath.getNameCount() >= 2
    ? gcsPath.resolveSibling(other)
    : GcsPath.fromUri("gs://" + gcsPath.getBucket() + "/").resolve(other);

if (path.getNameCount() < 2) { throw new IllegalArgumentException("Cannot resolve sibling of root path " + path); }

boolean canResolveSibling(GcsPath p) { return p.getNameCount() >= 2; }

try { return path.resolveSibling(other); } catch (UnsupportedOperationException e) { return GcsPath.fromUri("gs://" + ((GcsPath) path).getBucket() + "/").resolve(other); }

When it happens

Trigger: Calling resolveSibling(Path) or resolveSibling(String) on a GcsPath with fewer than two name components, e.g. on 'gs://bucket'.

Common situations: Generic path-joining code (e.g. computing sibling files, config-relative paths) applied to a bucket root URI; refactoring local file code to GCS paths without checking depth.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Can't get filename from root path in the bucket: %s
• Skipping dest existence is only supported within a bucket.
• GcsSeekableByteChannels are read-only and cannot be truncate
• GcsSeekableByteChannel are read-only and does not support wr
• Runner does not support draining.

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