{"record":{"id":"0c550b854f67ced9","repo":"apache/beam","slug":"file-spec-s-not-found","errorCode":null,"errorMessage":"File spec %s not found","messagePattern":"File spec (.+?) not found","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java","lineNumber":196,"sourceCode":"    }\n    return res;\n  }\n\n  /**\n   * Returns the {@link Metadata} for a single file resource. Expects a resource specification\n   * {@code spec} that matches a single result.\n   *\n   * @param spec a resource specification that matches exactly one result.\n   * @return the {@link Metadata} for the specified resource.\n   * @throws FileNotFoundException if the file resource is not found.\n   * @throws IOException in the event of an error in the inner call to {@link #match}, or if the\n   *     given spec does not match exactly 1 result.\n   */\n  public static Metadata matchSingleFileSpec(String spec) throws IOException {\n    List<MatchResult> matches = FileSystems.match(Collections.singletonList(spec));\n    MatchResult matchResult = Iterables.getOnlyElement(matches);\n    if (matchResult.status() == Status.NOT_FOUND) {\n      throw new FileNotFoundException(String.format(\"File spec %s not found\", spec));\n    } else if (matchResult.status() != Status.OK) {\n      throw new IOException(\n          String.format(\"Error matching file spec %s: status %s\", spec, matchResult.status()));\n    } else {\n      List<Metadata> metadata = matchResult.metadata();\n      if (metadata.size() != 1) {\n        throw new IOException(\n            String.format(\n                \"Expecting spec %s to match exactly one file, but matched %s: %s\",\n                spec, metadata.size(), metadata));\n      }\n      return metadata.get(0);\n    }\n  }\n\n  /**\n   * Returns {@link MatchResult MatchResults} for the given {@link ResourceId resourceIds}.\n   *","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java#L178-L214","documentation":"FileSystems.matchSingleFileSpec resolves a file spec via FileSystems.match and throws FileNotFoundException when the MatchResult status is NOT_FOUND, i.e. the glob/path matched no files on any registered filesystem.","triggerScenarios":"Calling FileSystems.matchSingleFileSpec(\"...\") with a path or glob that matches zero files: wrong bucket/path, typo, file deleted before matching, or no filesystem registered for the scheme (which surfaces as IllegalArgumentException first).","commonSituations":"GCS/S3/local paths with typos; expecting a file that another job hasn't produced yet; case-sensitivity mismatch on Linux local paths; staging files cleaned up before the pipeline runs.","solutions":["Verify the exact path/glob exists using gsutil/aws cli/ls before the call","Use FileSystems.match() with a glob and handle empty results instead of matchSingleFileSpec","Wrap in try-catch for FileNotFoundException and provide a fallback or clearer message","Check that the correct filesystem(s) are registered for the scheme"],"exampleFix":"// before\nMetadata md = FileSystems.matchSingleFileSpec(options.getInputFile());\n// after\nMatchResult res = FileSystems.match(Collections.singletonList(options.getInputFile())).get(0);\nif (res.status() != MatchResult.Status.OK || res.metadata().isEmpty()) {\n  throw new FileNotFoundException(\"Input not found: \" + options.getInputFile());\n}\nMetadata md = res.metadata().get(0);","handlingStrategy":"try-catch","validationCode":"MatchResult r = FileSystems.match(Collections.singletonList(spec)).get(0);\nboolean exists = r.status() == MatchResult.Status.OK && !r.metadata().isEmpty();","typeGuard":null,"tryCatchPattern":"try {\n  Metadata md = FileSystems.matchSingleFileSpec(spec);\n} catch (FileNotFoundException e) {\n  LOG.warn(\"Spec not found: {}\", spec);\n  // fallback: skip, wait, or fail with clearer context\n}","preventionTips":["Validate paths exist in a pre-flight check before the pipeline","Avoid globs in matchSingleFileSpec — use exact paths","Handle upstream job ordering so files exist before matching","Log the resolved spec for debugging path construction"],"tags":["java","apache-beam","filesystem","file-not-found","io"],"backgroundTag":"file-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}