What causes "Delete passed string argument instead of list: %s" in apache/beam?

Wrap the path in a list: FileSystems.delete(['gs://bucket/file'])

apache/beam · error · BeamIOError

Delete passed string argument instead of list: %s

Error message

Delete passed string argument instead of list: %s

What it means

FileSystems.delete() deletes a list of file paths, and BeamIOError is raised if the caller passes a bare string instead of a list of paths. The API intentionally rejects a single string because strings are iterable and would otherwise be treated as a list of characters, deleting wrong paths.

Source

Thrown at sdks/python/apache_beam/io/filesystems.py:374

    Raises:
      ``BeamIOError``: if path isn't a file or doesn't exist.
    """
    filesystem = FileSystems.get_filesystem(path)
    return filesystem.checksum(path)

  @staticmethod
  def delete(paths):
    """Deletes files or directories at the provided paths.
    Directories will be deleted recursively.

    Args:
      paths: list of paths that give the file objects to be deleted

    Raises:
      ``BeamIOError``: if any of the delete operations fail
    """
    if isinstance(paths, str):
      raise BeamIOError(
          'Delete passed string argument instead of list: %s' % paths)
    if len(paths) == 0:
      return
    filesystem = FileSystems.get_filesystem(paths[0])
    return filesystem.delete(paths)

  @staticmethod
  def get_chunk_size(path):
    """Get the correct chunk size for the FileSystem.

    Args:
      path: string path that needs to be checked.

    Returns: integer size for parallelization in the FS operations.
    """
    filesystem = FileSystems.get_filesystem(path)
    return filesystem.CHUNK_SIZE

View on GitHub (pinned to 12126d8942)

Solutions

Wrap the path in a list: FileSystems.delete(['gs://bucket/file'])
If the input may be a string, normalize it: paths = [paths] if isinstance(paths, str) else paths
Use FileSystems.delete with matchers like FileSystems.match results' metadata_list of path strings

Example fix

// before
FileSystems.delete('gs://bucket/file.txt')
// after
FileSystems.delete(['gs://bucket/file.txt'])

Defensive patterns

Strategy: type-guard

Validate before calling

def as_path_list(paths):
    if isinstance(paths, str):
        return [paths]
    return list(paths)
FileSystems.delete(as_path_list(my_path))

Type guard

def is_path_list(x):
    return isinstance(x, (list, tuple)) and all(isinstance(p, str) for p in x)

Try / catch

from apache_beam.io.filesystem import BeamIOError
try:
    FileSystems.delete(paths)
except BeamIOError as e:
    if 'string argument instead of list' in str(e):
        FileSystems.delete([paths])
    else:
        raise

Prevention

Always pass a list, even for a single file
Normalize str inputs to [str] in a helper before calling delete
Add unit tests covering single-path deletion

When it happens

Trigger: Calling apache_beam.io.filesystems.FileSystems.delete('gs://bucket/file') (a plain str) instead of a list of path strings.

Common situations: Developers deleting a single file commonly pass the path string directly; also happens when a variable may hold either one path or many.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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