apache/beam · error · FileNotFoundError

Found no files that match {self.path!r}

Error message

Found no files that match {self.path!r}

What it means

In the deferred text/CSV file source's expand(), FileSystems.match is called on the glob path with a limit; if the match returns no metadata (no files on the filesystem match the pattern), this error naming the path fires before any read is attempted. It means the glob matched zero files — typically a wrong path, wrong bucket, or missing permissions.

Source

Thrown at sdks/python/apache_beam/dataframe/io.py:281

      raise NotImplementedError('compression')
    if not isinstance(path, str):
      raise frame_base.WontImplementError('non-deferred')
    self.reader = reader
    self.path = path
    self.args = args
    self.kwargs = kwargs
    self.binary = binary
    self.incremental = incremental
    self.splitter = splitter
    self.filename_column = filename_column

  def expand(self, root):
    paths_pcoll = root | beam.Create([self.path])
    match = io.filesystems.FileSystems.match([self.path], limits=[1])[0]
    if not match.metadata_list:
      # TODO(https://github.com/apache/beam/issues/20858): This should be
      # allowed for streaming pipelines if user provides an explicit schema.
      raise FileNotFoundError(f"Found no files that match {self.path!r}")
    first_path = match.metadata_list[0].path
    with io.filesystems.FileSystems.open(first_path) as handle:
      if not self.binary:
        handle = TextIOWrapper(
            handle, encoding=self.kwargs.get("encoding", None))
      if self.incremental:
        with self.reader(handle, *self.args, **dict(self.kwargs,
                                                    chunksize=100)) as stream:
          sample = next(stream)
      else:
        sample = self.reader(handle, *self.args, **self.kwargs)
    if self.filename_column:
      sample[self.filename_column] = ''

    matches_pcoll = paths_pcoll | fileio.MatchAll()
    indices_pcoll = (
        matches_pcoll.pipeline
        | 'DoOnce' >> beam.Create([None])

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the path/glob manually (gsutil ls, aws s3 ls) and correct typos.
2. Confirm authentication/project so the filesystem can see the objects.
3. Ensure upstream files exist before the pipeline runs (ordering/dependency).

Example fix

// before
read_csv('gs://my-bucket/dat/*.csv')  # files are under dt=YYYY-MM-DD/*.csv
// after
read_csv('gs://my-bucket/dat/*/*.csv')

from apache_beam.io import filesystems
m = filesystems.FileSystems.match([path], limits=[1])[0]
if not m.metadata_list:
    raise FileNotFoundError(f'No files match {path}')

try:
    df = read_csv('gs://bucket/prefix/*.csv')
except FileNotFoundError:
    logging.error('Check path, credentials, and that inputs exist before launch')
    raise

When it happens

Trigger: read_csv('gs://bucket/prefix/*.csv') where no objects match, a misspelled bucket/path, wrong project credentials hiding the data, or running a batch pipeline before the producing job has written files.

Common situations: Typos in GCS/S3 paths; environment misconfiguration (wrong project); files written with different extension than the glob; race conditions where input isn't staged yet.

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

• src and dst files do not exist. src: %s, dst: %s
• Encountered an Atomic type that is not currently supported b
• Error completing file copies with retries, sample: from %s t
• Error trying to delete %s: %s
• Please specify a BigQuery table to read from.

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