{"record":{"id":"e2c81b4f0c219122","repo":"run-llama/llama_index","slug":"kg-rel-map-must-be-found-in-at-least-one-node","errorCode":null,"errorMessage":"kg_rel_map must be found in at least one Node.","messagePattern":"kg_rel_map must be found in at least one Node\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/knowledge_graph/retrievers.py","lineNumber":391,"sourceCode":"            excluded_embed_metadata_keys=[\"kg_rel_map\", \"kg_rel_texts\"],\n            excluded_llm_metadata_keys=[\"kg_rel_map\", \"kg_rel_texts\"],\n        )\n        # this node is constructed from rel_texts, give high confidence to avoid cutoff\n        sorted_nodes_with_scores.append(\n            NodeWithScore(node=rel_text_node, score=DEFAULT_NODE_SCORE)\n        )\n\n        return sorted_nodes_with_scores\n\n    def _get_metadata_for_response(\n        self, nodes: List[BaseNode]\n    ) -> Optional[Dict[str, Any]]:\n        \"\"\"Get metadata for response.\"\"\"\n        for node in nodes:\n            if node.metadata is None or \"kg_rel_map\" not in node.metadata:\n                continue\n            return node.metadata\n        raise ValueError(\"kg_rel_map must be found in at least one Node.\")\n\n\nDEFAULT_SYNONYM_EXPAND_TEMPLATE = \"\"\"\nGenerate synonyms or possible form of keywords up to {max_keywords} in total,\nconsidering possible cases of capitalization, pluralization, common expressions, etc.\nProvide all synonyms of keywords in comma-separated format: 'SYNONYMS: <keywords>'\nNote, result should be in one-line with only one 'SYNONYMS: ' prefix\n----\nKEYWORDS: {question}\n----\n\"\"\"\n\nDEFAULT_SYNONYM_EXPAND_PROMPT = PromptTemplate(\n    DEFAULT_SYNONYM_EXPAND_TEMPLATE,\n    prompt_type=PromptType.QUERY_KEYWORD_EXTRACT,\n)\n\n","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/knowledge_graph/retrievers.py#L373-L409","documentation":"KG table retrievers attach the graph context as node metadata under the key 'kg_rel_map'; _get_metadata_for_response scans the retrieved nodes for that key so the response synthesizer can cite the graph relations. If no retrieved node carries 'kg_rel_map' metadata, the method raises ValueError. This usually means retrieval produced no KG-augmented nodes (e.g. empty rel_map or custom nodes passed in).","triggerScenarios":"KGTableRetriever._get_metadata_for_response invoked when every retrieved node lacks the 'kg_rel_map' metadata key — typically the knowledge graph store returned an empty rel_map (no entities matched the query keywords) or nodes were synthesized/injected without KG metadata; also triggered by querying a KG index built with include_embeddings but a graph store that returns no relations.","commonSituations":"Querying a sparse or freshly built KnowledgeGraphIndex whose triplets share no keywords with the query; using a graph store (e.g. Nebula/Neo4j remote) that returns an empty rel_map due to connection or depth settings; custom retriever subclasses that override retrieval but reuse this metadata hook.","solutions":["Check the graph actually contains relevant entities: inspect kg_index.index_struct.table and the rel_map the store returns for the query keywords; broaden max_keywords or add more triplets/documents.","Verify the graph store connection and get_rel_map(subjs, depth, limit) settings so relation maps are actually returned.","If empty results are expected, subclass or wrap the retriever to return a 'no context' response instead of letting the metadata lookup raise."],"exampleFix":"# before\n# query with keywords that match no KG entities -> ValueError\nresponse = kg_index.as_query_engine().query(\"unrelated question\")\n\n# after\n# ensure the graph has content covering the query domain\nkg_index = KnowledgeGraphIndex.from_documents(docs, max_triplets_per_node=10)\nresponse = kg_index.as_query_engine().query(\"question about graph entities\")","handlingStrategy":"validation","validationCode":"# before querying, confirm the KG has entities matching typical queries\nsubjs = list(kg_index.index_struct.table.keys())\nrel_map = kg_index._graph_store.get_rel_map(subjs=subjs, depth=1, limit=5)\nassert rel_map, \"KG store returned no relations; retriever will fail on kg_rel_map lookup\"","typeGuard":null,"tryCatchPattern":"try:\n    response = kg_engine.query(q)\nexcept ValueError as e:\n    if \"kg_rel_map\" in str(e):\n        response = llm.complete(q)  # no KG context available; answer directly\n    else:\n        raise","preventionTips":["Verify the graph store is populated and reachable before serving queries.","Tune max_keywords/max_object_length so keyword extraction actually matches graph entities.","Monitor rel_map sizes in staging to catch empty-relation stores early."],"tags":["llama-index","knowledge-graph","retriever","metadata","empty-results"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}