cocoindex-io/cocoindex · error · ValueError

Invalid {kind}: {name!r}

Error message

Invalid {kind}: {name!r}

What it means

_validate_identifier raises ValueError when a name (identifier, collection name, index name, etc.) is not a string or fails the _IDENTIFIER_RE regex. zvec requires names matching the identifier pattern.

Source

Thrown at python/cocoindex/connectors/zvec/_target.py:87

_DOC_ID_CHECKER: TypeChecker[str] = TypeChecker(str)
_COLLECTION_KEY_CHECKER = TypeChecker(tuple[str, str])

RowT = TypeVar("RowT", default=dict[str, Any])


# zvec rejects names that don't match its internal rule. We guard with a
# conservative identifier allow-list before handing the name to zvec, which
# mirrors the input-safety guidance for other connectors and gives a clear error
# early.
_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")

# zvec additionally rejects collection names shorter than 3 characters.
_MIN_COLLECTION_NAME_LEN = 3


def _validate_identifier(name: str, kind: str = "identifier") -> None:
    if not isinstance(name, str) or not _IDENTIFIER_RE.match(name):
        raise ValueError(f"Invalid {kind}: {name!r}")


def _validate_collection_name(name: str) -> None:
    _validate_identifier(name, "collection name")
    if len(name) < _MIN_COLLECTION_NAME_LEN:
        raise ValueError(
            f"Invalid collection name {name!r}: zvec requires at least "
            f"{_MIN_COLLECTION_NAME_LEN} characters."
        )


# =============================================================================
# Connection
# =============================================================================


def _collection_option(enable_mmap: bool, *, read_only: bool = False) -> Any:
    return _zvec.CollectionOption(read_only=read_only, enable_mmap=enable_mmap)

View on GitHub (pinned to e84aa99b32)

Solutions

1. Use only [A-Za-z_][A-Za-z0-9_]-style names that match the identifier regex
2. Sanitize/transform programmatic names (e.g. replace '-' with '_')
3. Ensure the value is a str, not Path/int

Example fix

// before
collection_target(name=f"docs-{tenant_id}")
// after
collection_target(name=f"docs_{tenant_id}")

import re
IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
assert isinstance(name, str) and IDENT.match(name), f"bad name: {name!r}"

def is_valid_identifier(name: object) -> TypeGuard[str]:
    return isinstance(name, str) and bool(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name))

try:
    target = zvec.collection_target(name=name, ...)
except ValueError as e:
    if str(e).startswith("Invalid"):
        name = re.sub(r"\W", "_", name) or "collection"
        target = zvec.collection_target(name=name, ...)
    else:
        raise

When it happens

Trigger: Passing a collection/field name with invalid characters (spaces, dashes, leading digits, symbols), or a non-string value (e.g. an int or Path) as a name, via collection_target or derived from_class names.

Common situations: Building collection names from file paths or user input without sanitizing; dashes in names; programmatic names containing illegal characters.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid collection name {name!r}: zvec requires at least {_M
• {label} must contain only alphanumeric characters, hyphens,
• Invalid vector dimension for {name!r}: {vector_schema.size}
• Vector column {name!r} requires a VectorSchema (provide it v
• Column {name!r} cannot combine ZvecFtsType with ZvecType.

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/a8b6a434875c2020. Report an issue: GitHub.