What causes "Error when finding: ${filePath}" in apache/beam?

Verify the file exists at the exact path before calling (e.g. FileSystems.match or new File(path).exists() for local files).

apache/beam · error · java.lang.RuntimeException

Error when finding

Error message

Error when finding: ${filePath}

What it means

Thrown by openLocalFile when resolving and opening a file path via Beam's FileSystems layer fails with an IOException. The method matches the path, requires exactly one match, then opens the resulting ResourceId; any filesystem failure (missing file, bad scheme, IO error) is wrapped in this RuntimeException with the original path in the message.

Solutions

Verify the file exists at the exact path before calling (e.g. FileSystems.match or new File(path).exists() for local files).
Use a fully qualified absolute path including the scheme (file:///... or gs://bucket/...).
Avoid wildcards, or ensure the glob matches exactly one file.
Register the appropriate filesystem on the pipeline (e.g. add GCS dependencies / --gcpTempLocation setup) if using a non-local scheme.
Inspect the wrapped IOException (getCause()) for the underlying reason.

Example fix

// before
openLocalFile("model.proto");
// after
openLocalFile("file:///opt/config/model.proto"); // absolute, single existing file

Defensive patterns

Strategy: validation

Validate before calling

MatchResult result = FileSystems.match(filePath);
if (result.metadata().size() != 1) {
  throw new IllegalArgumentException("Path must match exactly one file: " + filePath);
}

Try / catch

try { ch = openLocalFile(path); } catch (RuntimeException e) { log.error("file open failed for {}: {}", path, e.getCause(), e); throw new UncheckedIOException(e.getCause()); }

Prevention

Always use absolute paths with explicit scheme.
Check file existence with FileSystems.match before opening.
Avoid glob patterns that can match multiple files.
Register required filesystems (GCS/HDFS) before use.

When it happens

Trigger: Calling getFileByteChannel/openLocalFile with a path that does not match any file in the configured filesystem, a path with an unregistered filesystem scheme, or when FileSystems.open() fails during I/O. Also thrown when a glob matches more or fewer than exactly 1 file, causing the checkArgument to fail first.

Common situations: Reading a model or proto descriptor file from local disk or GCS where the file was deleted or the path is relative instead of absolute; passing 'gs://' paths without the GCS filesystem on the classpath; using a wildcard glob that matches 0 or multiple files.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/extensions/protobuf/src/main/java/org/apache/beam/sdk/extensions/protobuf/ProtoByteUtils.java:325

   * @param filePath The local file path.
   * @return A ReadableByteChannel for reading from the specified local file.
   * @throws IllegalArgumentException If no files match the specified pattern or if more than one
   *     file matches.
   */
  private static ReadableByteChannel openLocalFile(String filePath) {
    try {
      MatchResult result = FileSystems.match(filePath);
      checkArgument(
          result.status() == MatchResult.Status.OK && !result.metadata().isEmpty(),
          "Failed to match any files with the pattern: " + filePath);

      List<ResourceId> rId =
          result.metadata().stream().map(MatchResult.Metadata::resourceId).collect(toList());

      checkArgument(rId.size() == 1, "Expected exactly 1 file, but got %s files.", rId.size());
      return FileSystems.open(rId.get(0));
    } catch (IOException e) {
      throw new RuntimeException("Error when finding: " + filePath, e);
    }
  }

  /**
   * Extracts the bucket name from a Google Cloud Storage (GCS) file path.
   *
   * @param gcsPath The GCS file path (e.g., "gs://your-bucket-name/your-object-name").
   * @return The bucket name extracted from the GCS path.
   */
  private static String getBucketName(String gcsPath) {
    int startIndex = "gs://".length();
    int endIndex = gcsPath.indexOf('/', startIndex);
    return gcsPath.substring(startIndex, endIndex);
  }

  /**
   * Extracts the object name from a Google Cloud Storage (GCS) file path.
   *

View on GitHub (pinned to 12126d8942)