microsoft/graphrag · error · ValueError

Container name must be between 3 and 63 characters long and

Error message

Container name must be between 3 and 63 characters long and contain only lowercase letters, numbers, or hyphens. Name provided was {container_name}.

What it means

AzureBlobStorage validates container names against Azure's rules: 3-63 characters, only lowercase letters, digits, and hyphens that are not leading/trailing (no consecutive-hyphen-friendly guarantees beyond the regex). A name failing the regex raises ValueError before the client is created.

Source

Thrown at packages/graphrag-storage/graphrag_storage/azure_blob_storage.py:278

        - Start with a letter or number
        - All letters used in blob container names must be lowercase.
        - Contain only letters, numbers, or the hyphen.
        - Consecutive hyphens are not permitted.
        - Cannot end with a hyphen.

    Args:
    -----
    container_name (str)
        The blob container name to be validated.

    Returns
    -------
        bool: True if valid, False otherwise.
    """
    # Match alphanumeric or single hyphen not at the start or end, repeated 3-63 times.
    if not re.match(r"^(?:[0-9a-z]|(?<!^)-(?!$)){3,63}$", container_name):
        msg = f"Container name must be between 3 and 63 characters long and contain only lowercase letters, numbers, or hyphens. Name provided was {container_name}."
        raise ValueError(msg)

View on GitHub (pinned to f40e9a26ce)

Solutions

Normalize the name: lowercase, replace '_'/'.'/'/' with '-', strip leading/trailing hyphens, truncate to 63 chars
Validate names at config load time with the same regex before constructing storage
For names that can't be sanitized losslessly, maintain an explicit mapping table
Add a unit check if container names come from external input

Example fix

# before
storage = AzureBlobStorage(container_name='My_Project.Cache')  # ValueError

# after
import re
name = re.sub(r'[^a-z0-9-]', '-', 'My_Project.Cache'.lower()).strip('-')[:63]
storage = AzureBlobStorage(container_name=name)

Defensive patterns

Strategy: validation

Validate before calling

import re
CONTAINER_RE = re.compile(r'^(?:[0-9a-z]|(?<!^)-(?!$)){3,63}$')
def valid_container_name(name: str) -> bool:
    return bool(CONTAINER_RE.match(name))
assert valid_container_name(container_name)

Type guard

import re
def is_valid_container_name(name: str) -> bool:
    return bool(re.match(r'^(?:[0-9a-z]|(?<!^)-(?!$)){3,63}$', name))

Try / catch

try:
    s = AzureBlobStorage(container_name=name, ...)
except ValueError as e:
    if 'Container name' in str(e):
        name = re.sub(r'[^a-z0-9-]', '-', name.lower()).strip('-')[:63]
        s = AzureBlobStorage(container_name=name, ...)
    else:
        raise

Prevention

Sanitize any derived container name at config load time
Add the same regex check in CI for config values coming from user input

When it happens

Trigger: Passing container_name with uppercase letters, underscores, dots, a leading/trailing hyphen, or fewer than 3 / more than 63 characters to AzureBlobStorage.__init__.

Common situations: Deriving container names from user input, dataset names, or project slugs containing '_' or capitals (common on GitHub repos), or a base_dir/container split that accidentally includes a slash.

Related errors

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/6b2e8cd66b0e89b1. Report an issue: GitHub.