chroma-core/chroma · error · ValueError

Cannot create index on special key '{key}'. This key is mana

Error message

Cannot create index on special key '{key}'. This key is managed automatically by the system. Invoke create_index(VectorIndexConfig(...)) without specifying a key to configure the vector index globally.

What it means

Error "Cannot create index on special key '{key}'. This key is managed automatically by the system. Invoke create_index(VectorIndexConfig(...)) without specifying a key to configure the vector index globally." thrown in chroma-core/chroma.

Source

Thrown at chromadb/api/types.py:2144

        config: Optional[IndexConfig] = None,
        key: Optional[Union[str, "Key"]] = None,
    ) -> "Schema":
        """Create an index configuration."""
        # Convert Key to string if provided
        from chromadb.execution.expression.operator import Key as KeyType

        if key is not None and isinstance(key, KeyType):
            key = key.name

        # Disallow config=None and key=None - too dangerous
        if config is None and key is None:
            raise ValueError(
                "Cannot enable all index types globally. Must specify either config or key."
            )

        # Disallow using special internal key #embedding
        if key is not None and key == EMBEDDING_KEY:
            raise ValueError(
                f"Cannot create index on special key '{key}'. This key is managed automatically by the system. Invoke create_index(VectorIndexConfig(...)) without specifying a key to configure the vector index globally."
            )

        # Only allow #document with FtsIndexConfig
        if key == DOCUMENT_KEY and not isinstance(config, FtsIndexConfig):
            raise ValueError(
                f"Cannot create index on special key '{key}' with this config. "
                "Only FtsIndexConfig is allowed for #document."
            )

        # Disallow any key starting with # (except #document which allows FTS)
        if key is not None and key.startswith("#") and key != DOCUMENT_KEY:
            raise ValueError(
                "key cannot begin with '#'. "
                "Keys starting with '#' are reserved for system use."
            )

        # Special handling for vector index

View on GitHub (pinned to aecdd12c8a)

When it happens

Trigger: Thrown at chromadb/api/types.py:2144 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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