{"record":{"id":"14dc1c19efbdc21d","repo":"apache/beam","slug":"error-when-finding-filepath","errorCode":null,"errorMessage":"Error when finding: ${filePath}","messagePattern":"Error when finding: (.+?)","errorType":"exception","errorClass":"java.lang.RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/protobuf/src/main/java/org/apache/beam/sdk/extensions/protobuf/ProtoByteUtils.java","lineNumber":325,"sourceCode":"   * @param filePath The local file path.\n   * @return A ReadableByteChannel for reading from the specified local file.\n   * @throws IllegalArgumentException If no files match the specified pattern or if more than one\n   *     file matches.\n   */\n  private static ReadableByteChannel openLocalFile(String filePath) {\n    try {\n      MatchResult result = FileSystems.match(filePath);\n      checkArgument(\n          result.status() == MatchResult.Status.OK && !result.metadata().isEmpty(),\n          \"Failed to match any files with the pattern: \" + filePath);\n\n      List<ResourceId> rId =\n          result.metadata().stream().map(MatchResult.Metadata::resourceId).collect(toList());\n\n      checkArgument(rId.size() == 1, \"Expected exactly 1 file, but got %s files.\", rId.size());\n      return FileSystems.open(rId.get(0));\n    } catch (IOException e) {\n      throw new RuntimeException(\"Error when finding: \" + filePath, e);\n    }\n  }\n\n  /**\n   * Extracts the bucket name from a Google Cloud Storage (GCS) file path.\n   *\n   * @param gcsPath The GCS file path (e.g., \"gs://your-bucket-name/your-object-name\").\n   * @return The bucket name extracted from the GCS path.\n   */\n  private static String getBucketName(String gcsPath) {\n    int startIndex = \"gs://\".length();\n    int endIndex = gcsPath.indexOf('/', startIndex);\n    return gcsPath.substring(startIndex, endIndex);\n  }\n\n  /**\n   * Extracts the object name from a Google Cloud Storage (GCS) file path.\n   *","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/protobuf/src/main/java/org/apache/beam/sdk/extensions/protobuf/ProtoByteUtils.java#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nopenLocalFile(\"model.proto\");\n// after\nopenLocalFile(\"file:///opt/config/model.proto\"); // absolute, single existing file","handlingStrategy":"validation","validationCode":"MatchResult result = FileSystems.match(filePath);\nif (result.metadata().size() != 1) {\n  throw new IllegalArgumentException(\"Path must match exactly one file: \" + filePath);\n}","typeGuard":null,"tryCatchPattern":"try { ch = openLocalFile(path); } catch (RuntimeException e) { log.error(\"file open failed for {}: {}\", path, e.getCause(), e); throw new UncheckedIOException(e.getCause()); }","preventionTips":["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."],"tags":["java","filesystem","io"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}