apache/beam · error · ValueError

Basepath %r must be an Azure Blob Storage path.

Error message

Basepath %r must be an Azure Blob Storage path.

What it means

BlobStorageFileSystem.join validates that the base path starts with the Azure prefix 'az://' before combining path components; otherwise it raises ValueError. This guards against mixing local or other-cloud paths into Azure Blob Storage path math.

Solutions

1. Prefix the base path with 'az://', e.g. 'az://container/blob'.
2. Convert https://account.blob.core.windows.net/container/key style URLs to 'az://container/key'.
3. Normalize/validate incoming paths with a helper that asserts the 'az://' prefix before joining.

Example fix

// before
p = BlobStorageFileSystem.join('https://acct.blob.core.windows.net/c', 'f')  # ValueError
// after
p = BlobStorageFileSystem.join('az://c', 'f')

if not basepath.startswith('az://'):
    basepath = 'az://' + basepath.lstrip('/')

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

try:
    p = BlobStorageFileSystem.join(base, name)
except ValueError as e:
    logging.error("bad azure basepath: %s", e)
    p = BlobStorageFileSystem.join('az://' + base, name)

When it happens

Trigger: Calling BlobStorageFileSystem.join('wasbs://.../path', 'file') or join('/local/path', 'f') — any basepath not beginning with 'az://'.

Common situations: Using account-URL style paths (https://account.blob.core.windows.net/container) or the older wasb:/wasbs: schemes instead of 'az://'; passing a local temp directory as basepath; Beam MatchAll results from another filesystem.

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

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

Appendix: source

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

    self._pipeline_options = pipeline_options

  @classmethod
  def scheme(cls):
    """URI scheme for the FileSystem
    """
    return 'azfs'

  def join(self, basepath, *paths):
    """Join two or more pathname components for the filesystem

    Args:
      basepath: string path of the first component of the path
      paths: path components to be added

    Returns: full path after combining all the passed components
    """
    if not basepath.startswith(BlobStorageFileSystem.AZURE_FILE_SYSTEM_PREFIX):
      raise ValueError(
          'Basepath %r must be an Azure Blob Storage path.' % basepath)

    path = basepath
    for p in paths:
      path = path.rstrip('/') + '/' + p.lstrip('/')
    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

View on GitHub (pinned to 12126d8942)