microsoft/graphrag · error · ValueError

Invalid EntityVectorStoreKey: {value}

Error message

Invalid EntityVectorStoreKey: {value}

What it means

EntityVectorStoreKey.from_string parses the configured vector-store key type for entity search; only 'id' and 'title' are valid. Any other string (e.g. 'name', 'ID', or a typo) raises ValueError. This value typically comes from the query config's vector store key setting.

Source

Thrown at packages/graphrag/graphrag/query/context_builder/entity_extraction.py:38

    from graphrag_llm.embedding import LLMEmbedding


class EntityVectorStoreKey(str, Enum):
    """Keys used as ids in the entity embedding vectorstores."""

    ID = "id"
    TITLE = "title"

    @staticmethod
    def from_string(value: str) -> "EntityVectorStoreKey":
        """Convert string to EntityVectorStoreKey."""
        if value == "id":
            return EntityVectorStoreKey.ID
        if value == "title":
            return EntityVectorStoreKey.TITLE

        msg = f"Invalid EntityVectorStoreKey: {value}"
        raise ValueError(msg)


def map_query_to_entities(
    query: str,
    text_embedding_vectorstore: VectorStore,
    text_embedder: "LLMEmbedding",
    all_entities_dict: dict[str, Entity],
    embedding_vectorstore_key: str = EntityVectorStoreKey.ID,
    include_entity_names: list[str] | None = None,
    exclude_entity_names: list[str] | None = None,
    k: int = 10,
    oversample_scaler: int = 2,
) -> list[Entity]:
    """Extract entities that match a given query using semantic similarity of text embeddings of query and entity descriptions."""
    if include_entity_names is None:
        include_entity_names = []
    if exclude_entity_names is None:
        exclude_entity_names = []

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set the vector store key to exactly 'title' or 'id' in your query settings/config
2. If calling from_string directly, validate/normalize input to lowercase first
3. Check settings.yaml under vector_stores default_vector_store.key

Example fix

# before
vector_store_kwargs={'key': 'name'}
# after
vector_store_kwargs={'key': 'title'}

key = (cfg_key or 'title').lower()
if key not in ('id', 'title'):
    key = 'title'
EntityVectorStoreKey.from_string(key)

def is_valid_store_key(v: object) -> bool:
    return isinstance(v, str) and v in ('id', 'title')

When it happens

Trigger: Running a local/global query with vector store config where key is misspelled or wrong case (e.g. 'Name', 'entity_id'); passing a custom string through code that calls from_string directly.

Common situations: Editing settings.yaml and changing the entities vectorstore key to something not supported; upgrading GraphRAG versions where valid keys changed; copy-pasted config from other projects.

Related errors

• No storage account blob url provided for blob storage.
• Invalid Role: {value}
• TemplateEngineConfig.template_manager '{strategy}' is not re
• request_id needs to be passed as a keyword argument
• TokenizerConfig.type '{strategy}' is not registered in the T

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/48ae371628bd100c. Report an issue: GitHub.