apache/beam · error · FileNotFoundException

File spec %s not found

Error message

File spec %s not found

What it means

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.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java:196

    }
    return res;
  }

  /**
   * Returns the {@link Metadata} for a single file resource. Expects a resource specification
   * {@code spec} that matches a single result.
   *
   * @param spec a resource specification that matches exactly one result.
   * @return the {@link Metadata} for the specified resource.
   * @throws FileNotFoundException if the file resource is not found.
   * @throws IOException in the event of an error in the inner call to {@link #match}, or if the
   *     given spec does not match exactly 1 result.
   */
  public static Metadata matchSingleFileSpec(String spec) throws IOException {
    List<MatchResult> matches = FileSystems.match(Collections.singletonList(spec));
    MatchResult matchResult = Iterables.getOnlyElement(matches);
    if (matchResult.status() == Status.NOT_FOUND) {
      throw new FileNotFoundException(String.format("File spec %s not found", spec));
    } else if (matchResult.status() != Status.OK) {
      throw new IOException(
          String.format("Error matching file spec %s: status %s", spec, matchResult.status()));
    } else {
      List<Metadata> metadata = matchResult.metadata();
      if (metadata.size() != 1) {
        throw new IOException(
            String.format(
                "Expecting spec %s to match exactly one file, but matched %s: %s",
                spec, metadata.size(), metadata));
      }
      return metadata.get(0);
    }
  }

  /**
   * Returns {@link MatchResult MatchResults} for the given {@link ResourceId resourceIds}.
   *

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the exact path/glob exists using gsutil/aws cli/ls before the call
2. Use FileSystems.match() with a glob and handle empty results instead of matchSingleFileSpec
3. Wrap in try-catch for FileNotFoundException and provide a fallback or clearer message
4. Check that the correct filesystem(s) are registered for the scheme

Example fix

// before
Metadata md = FileSystems.matchSingleFileSpec(options.getInputFile());
// after
MatchResult res = FileSystems.match(Collections.singletonList(options.getInputFile())).get(0);
if (res.status() != MatchResult.Status.OK || res.metadata().isEmpty()) {
  throw new FileNotFoundException("Input not found: " + options.getInputFile());
}
Metadata md = res.metadata().get(0);

MatchResult r = FileSystems.match(Collections.singletonList(spec)).get(0);
boolean exists = r.status() == MatchResult.Status.OK && !r.metadata().isEmpty();

try {
  Metadata md = FileSystems.matchSingleFileSpec(spec);
} catch (FileNotFoundException e) {
  LOG.warn("Spec not found: {}", spec);
  // fallback: skip, wait, or fail with clearer context
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Error matching file spec %s: status %s
• Failed to get metadata from MatchResult: %s.
• OffsetRetainer: failed to read offset from . Delete the file
• Un-globbable filesystem.
• Read-only filesystem.

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