apache/beam · error · ValueError

Invalid path

Error message

Invalid path: %s

What it means

After prefix validation, BlobStorageFileSystem.split returns (parent, name) based on the last '/'. If the only '/' is exactly at the end of the 'az://' prefix (last_sep == 0), there is no parent or name to return, so it raises ValueError('Invalid path').

Solutions

1. Pass a full path of the form 'az://container/blob' including a non-root component.
2. Check for the degenerate root path before calling split and handle it separately.
3. Ensure upstream path manipulation does not strip the container name.

Example fix

// before
dir, name = BlobStorageFileSystem.split('az://')  # ValueError
// after
if path.rstrip('/') == 'az://':
    return ('', '')
dir, name = BlobStorageFileSystem.split(path)

if path in ('az://', 'az:///', ''):
    raise ValueError('root az:// path cannot be split into parent/name')

def is_splittable_azure_path(p):
    return isinstance(p, str) and p.startswith('az://') and '/' in p[5:]

try:
    parent, name = BlobStorageFileSystem.split(path)
except ValueError:
    parent, name = '', ''  # degenerate root path

When it happens

Trigger: Calling split('az://') or split('az:///') — a path with a container-less, slash-only root and no file component.

Common situations: Parsing an empty or root-level path; a caller stripping the container from a path before splitting; off-by-one when slicing paths in upstream code.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Basepath %r must be an Azure Blob Storage path.
• Path %r must be Azure Blob Storage path.
• List operation failed
• Unable to copy unequal number of sources and destinations.
• Basepath %r must be S3 path.

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

Appendix: source

Thrown at sdks/python/apache_beam/io/azure/blobstoragefilesystem.py:97

    Returns:
      a pair of path components as strings.
    """
    path = path.strip()
    if not path.startswith(BlobStorageFileSystem.AZURE_FILE_SYSTEM_PREFIX):
      raise ValueError('Path %r must be Azure Blob Storage path.' % path)

    prefix_len = len(BlobStorageFileSystem.AZURE_FILE_SYSTEM_PREFIX)
    last_sep = path[prefix_len:].rfind('/')
    if last_sep >= 0:
      last_sep += prefix_len

    if last_sep > 0:
      return (path[:last_sep], path[last_sep + 1:])
    elif last_sep < 0:
      return (path, '')
    else:
      raise ValueError('Invalid path: %s' % path)

  def mkdirs(self, path):
    """Recursively create directories for the provided path.

    Args:
      path: string path of the directory structure that should be created

    Raises:
      IOError: if leaf directory already exists.
    """
    pass

  def has_dirs(self):
    """Whether this FileSystem supports directories."""
    return False

  def _list(self, dir_or_prefix):
    """List files in a location.

View on GitHub (pinned to 12126d8942)