chroma-core/chroma · error · ValueError

Expected collection name that (1) contains 3-63 characters,

Error message

Expected collection name that (1) contains 3-63 characters, (2) starts and ends with an alphanumeric character, (3) otherwise contains only alphanumeric characters, underscores or hyphens (-), (4) contains no two consecutive periods (..) and (5) is not a valid IPv4 address, got {index_name}

What it means

check_index_name (chromadb/api/segment.py:105) validates collection names with S3-bucket-style rules. This raise site (line 109) fires when the name is shorter than 3 or longer than 63 characters. The same message is reused by the charset, double-period, and IPv4 checks, so the text alone does not say which rule failed.

Source

Thrown at chromadb/api/segment.py:109

T = TypeVar("T", bound=Callable[..., Any])

logger = logging.getLogger(__name__)


# mimics s3 bucket requirements for naming
def check_index_name(index_name: str) -> None:
    msg = (
        "Expected collection name that "
        "(1) contains 3-63 characters, "
        "(2) starts and ends with an alphanumeric character, "
        "(3) otherwise contains only alphanumeric characters, underscores or hyphens (-), "
        "(4) contains no two consecutive periods (..) and "
        "(5) is not a valid IPv4 address, "
        f"got {index_name}"
    )
    if len(index_name) < 3 or len(index_name) > 63:
        raise ValueError(msg)
    if not re.match("^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$", index_name):
        raise ValueError(msg)
    if ".." in index_name:
        raise ValueError(msg)
    if re.match("^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$", index_name):
        raise ValueError(msg)


def rate_limit(func: T) -> T:
    @wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        self = args[0]
        return self._rate_limit_enforcer.rate_limit(func)(*args, **kwargs)

    return wrapper  # type: ignore


class SegmentAPI(ServerAPI):

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Rename the collection to 3-63 characters (e.g. 'ab' -> 'ab_collection')
2. When generating names programmatically, pad or prefix short identifiers and clamp total length to <= 63
3. Pre-validate with the same rule (see validation helper) before calling create_collection

Example fix

# before
client.create_collection(name='ab')  # ValueError: 2 chars

# after
client.create_collection(name='ab_collection')  # 13 chars - valid

import re

def valid_collection_name(name: str) -> bool:
    """Mirror chromadb.api.segment.check_index_name."""
    if not (3 <= len(name) <= 63):
        return False
    if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$', name):
        return False
    if '..' in name:
        return False
    if re.match(r'^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$', name):
        return False
    return True

# use before creating:
# assert valid_collection_name(name), f'bad collection name: {name!r}'

from typing import Tuple

def check_name_or_raise(name: str) -> Tuple[bool, str]:
    if len(name) < 3 or len(name) > 63:
        return False, 'length must be 3-63'
    return True, ''

try:
    client.create_collection(name=name)
except ValueError as e:
    if 'Expected collection name' in str(e):
        name = f'app-{name}'[:63].rstrip('._-')
        client.create_collection(name=name)
    else:
        raise

When it happens

Trigger: client.create_collection(name='ab') (2 chars) or a name longer than 63 chars; also client.get_or_create_collection / any API path that validates a new collection name. Only the length branch - len(name) < 3 or len(name) > 63 - produces this instance.

Common situations: Auto-generating collection names from user IDs, dates, or slugs that end up 1-2 characters; truncating names with [:60] plus a suffix pushing past 63; test fixtures using names like 't' or 'c1'.

Related errors

• Database name must be at least 3 characters long
• Tenant name must be at least 3 characters long
• MinK keys cannot be empty
• MaxK keys cannot be empty
• GroupBy keys cannot be empty

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/7c2ada9f16384022. Report an issue: GitHub.