{"record":{"id":"6d188093d7c3e347","repo":"headroomlabs-ai/headroom","slug":"metadata-file-not-found-meta-path","errorCode":null,"errorMessage":"Metadata file not found: {meta_path}","messagePattern":"Metadata file not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"headroom/memory/adapters/hnsw.py","lineNumber":854,"sourceCode":"        \"\"\"Load the index from disk.\n\n        Loads both the HNSW index and all metadata/mappings.\n\n        Args:\n            path: Base path for the saved files.\n\n        Raises:\n            FileNotFoundError: If the index files don't exist.\n            ValueError: If the saved dimension doesn't match.\n        \"\"\"\n        path = Path(path)\n        hnsw_path = path.with_suffix(\".hnsw\")\n        meta_path = path.with_suffix(\".meta\")\n\n        if not hnsw_path.exists():\n            raise FileNotFoundError(f\"HNSW index not found: {hnsw_path}\")\n        if not meta_path.exists():\n            raise FileNotFoundError(f\"Metadata file not found: {meta_path}\")\n\n        # Load metadata first to get parameters\n        with open(meta_path) as f:\n            meta_data = json.load(f)\n\n        # Verify dimension matches\n        saved_dimension = meta_data[\"dimension\"]\n        if saved_dimension != self._dimension:\n            raise ValueError(\n                f\"Saved index dimension {saved_dimension} does not match \"\n                f\"current dimension {self._dimension}\"\n            )\n\n        with self._lock:\n            # Update parameters\n            self._max_elements = meta_data[\"max_elements\"]\n            self._ef_construction = meta_data[\"ef_construction\"]\n            self._m = meta_data[\"m\"]","sourceCodeStart":836,"sourceCodeEnd":872,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/adapters/hnsw.py#L836-L872","documentation":"Raised by HNSWVectorIndex.load_index when the .hnsw graph file exists but the companion .meta metadata file does not. The metadata file stores dimension and construction parameters needed to reconstruct the index, so a lone graph file is unusable.","triggerScenarios":"A .hnsw file was copied or restored without its .meta sibling; partial writes or interrupted save_index; manual cleanup that deleted only one of the two files.","commonSituations":"Backup/restore scripts that glob only *.hnsw; sync tools excluding the .meta extension; crash between writing the two files during save_index.","solutions":["Keep .hnsw and .meta together — copy/restore both files as a pair.","If the .meta is lost, rebuild the index from source memories rather than trying to hand-craft metadata.","Make saves atomic (write to temp files, then rename both) to avoid half-written pairs."],"exampleFix":"// before\nawait index.load_index(path)\n\n// after\nif path.with_suffix('.hnsw').exists() and path.with_suffix('.meta').exists():\n    await index.load_index(path)\nelse:\n    await rebuild_index(index, memories)","handlingStrategy":"type-guard","validationCode":"if not (path.with_suffix('.hnsw').exists() and path.with_suffix('.meta').exists()):\n    await rebuild_index(index, memories)","typeGuard":"def index_pair_complete(base: Path) -> bool:\n    return base.with_suffix('.hnsw').exists() and base.with_suffix('.meta').exists()","tryCatchPattern":"try:\n    await index.load_index(path)\nexcept FileNotFoundError as e:\n    logger.warning(\"incomplete index at %s: %s; rebuilding\", path, e)\n    await rebuild_index(index, memories)","preventionTips":["Always move/copy .hnsw and .meta as a pair in backup and deploy scripts.","Write index files atomically (temp file + rename) to avoid half-saved pairs."],"tags":["hnsw","persistence","file-not-found","metadata"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}