cocoindex-io/cocoindex · error · ValueError

Invalid collection name {name!r}: zvec requires at least {_M

Error message

Invalid collection name {name!r}: zvec requires at least {_MIN_COLLECTION_NAME_LEN} characters.

What it means

Pre-flight guard before handing a collection name to the zvec engine. zvec silently rejects names violating its internal rules, so the connector applies a conservative identifier allow-list (^[A-Za-z_][A-Za-z0-9_]*$) and a minimum length of 3 to fail early with a clear message. This specific error fires when the name passes the regex but is shorter than 3 characters (e.g. 'ab'). Pick a longer, alphanumeric/underscore collection name.

Source

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

# 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)


@dataclass
class ManagedConnection:
    """A handle to a base directory holding zvec collections.

View on GitHub (pinned to e84aa99b32)

Solutions

1. Use a collection name of at least 3 characters
2. Prefix short names, e.g. f"col_{name}"
3. Add a length check before creating collections

Example fix

// before
this.collection_target(name="a")
// after
this.collection_target(name="docs_a")

if len(name) < 3:
    name = name.ljust(3, "_")  # or choose a longer name

def is_valid_collection_name(name: object) -> TypeGuard[str]:
    return isinstance(name, str) and len(name) >= 3 and bool(re.match(r"[A-Za-z_]", name))

try:
    target = zvec.collection_target(name=name, ...)
except ValueError as e:
    if "at least 3 characters" in str(e):
        name = f"col_{name}"
        target = zvec.collection_target(name=name, ...)
    else:
        raise

When it happens

Trigger: Creating a collection whose name is 1-2 characters long, e.g. collection_target(name="a") or name="db".

Common situations: Using short aliases, single-letter test names, or truncated identifiers generated from other data.

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 {kind}: {name!r}
• {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/87a5d5b1335d78fb. Report an issue: GitHub.