apache/beam · error · ValueError

Path %r must be Azure Blob Storage path.

Error message

Path %r must be Azure Blob Storage path.

What it means

BlobStorageFileSystem.split divides an 'az://' path into (directory, file) components but first requires the path to carry the Azure 'az://' prefix; otherwise ValueError. It keeps filesystem-specific path parsing from silently operating on foreign paths.

Solutions

1. Ensure the path starts with 'az://' before calling split.
2. Map wasb(s):// and https:// blob URLs to az:// form first.
3. Guard with a startswith check and raise a clear error for callers.

Example fix

// before
dir, name = BlobStorageFileSystem.split('wasbs://c/blob')  # ValueError
// after
path = path.replace('wasbs://', 'az://', 1)
dir, name = BlobStorageFileSystem.split(path)

if not path.startswith('az://'):
    raise ValueError(f"expected az:// path, got {path!r}")

def is_azure_path(p):
    return isinstance(p, str) and p.startswith('az://')

try:
    parent, name = BlobStorageFileSystem.split(path)
except ValueError:
    path = 'az://' + path.lstrip('/')
    parent, name = BlobStorageFileSystem.split(path)

When it happens

Trigger: Calling BlobStorageFileSystem.split('wasb://container/blob'), split('/mnt/data/file'), or split on a bare container name.

Common situations: Mixing wasb/wasbs legacy scheme paths with the az:// filesystem; handling user-supplied paths without normalization; string manipulation that stripped the scheme earlier in a pipeline.

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.
• Invalid 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/5bdb629bb04c0e7e. Report an issue: GitHub.

Appendix: source

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

    return path

  def split(self, path):
    """Splits the given path into two parts.

    Splits the path into a pair (head, tail) such that tail contains the last
    component of the path and head contains everything up to that.
    For file-systems other than the local file-system, head should include the
    prefix.

    Args:
      path: path as a string

    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

View on GitHub (pinned to 12126d8942)