chroma-core/chroma · error · ValueError

Cannot create index on special key '{key}' with this config.

Error message

Cannot create index on special key '{key}' with this config. Only FtsIndexConfig is allowed for #document.

What it means

Error "Cannot create index on special key '{key}' with this config. Only FtsIndexConfig is allowed for #document." thrown in chroma-core/chroma.

Source

Thrown at chromadb/api/types.py:2150

        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
        if isinstance(config, VectorIndexConfig):
            if key is None:
                # Allow setting vector config globally - it applies to defaults and #embedding
                # but doesn't change enabled state (vector index is always enabled on #embedding)
                self._set_vector_index_config(config)
                return self

View on GitHub (pinned to aecdd12c8a)

When it happens

Trigger: Thrown at chromadb/api/types.py:2150 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/5324e3ee2cee3cc8. Report an issue: GitHub.