{"record":{"id":"3427bca41f300432","repo":"headroomlabs-ai/headroom","slug":"hnswlib-is-required-for-hnswvectorindex-install-w","errorCode":null,"errorMessage":"hnswlib is required for HNSWVectorIndex. Install with: pip install hnswlib\nNote: hnswlib requires C++ compilation and may not be available on all platforms (crashes with SIGILL on CPUs without AVX support).","messagePattern":"hnswlib is required for HNSWVectorIndex\\. Install with: pip install hnswlib\nNote: hnswlib requires C\\+\\+ compilation and may not be available on all platforms \\(crashes with SIGILL on CPUs without AVX support\\)\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/memory/adapters/hnsw.py","lineNumber":261,"sourceCode":"            ef_construction: HNSW construction parameter. Higher = better quality,\n                           slower construction. Default: 200\n            m: HNSW links per element. Higher = better recall, more memory.\n               Default: 16\n            ef_search: HNSW search parameter. Higher = better recall, slower\n                      search. Default: 50\n            auto_save: If True and save_path is set, automatically save\n                      index after modifications.\n            save_path: Path for auto-save operations. Required if auto_save=True.\n            max_entries: Soft limit on number of entries. When reached,\n                        lowest importance entries are evicted. None = unbounded.\n            eviction_batch_size: Number of entries to evict when limit is reached.\n\n        Raises:\n            ValueError: If auto_save is True but save_path is not provided.\n            ImportError: If hnswlib is not installed.\n        \"\"\"\n        if not _check_hnswlib_available():\n            raise ImportError(\n                \"hnswlib is required for HNSWVectorIndex. \"\n                \"Install with: pip install hnswlib\\n\"\n                \"Note: hnswlib requires C++ compilation and may not be \"\n                \"available on all platforms (crashes with SIGILL on CPUs \"\n                \"without AVX support).\"\n            )\n\n        if auto_save and save_path is None:\n            raise ValueError(\"save_path must be provided when auto_save is True\")\n\n        self._dimension = dimension\n        self._max_elements = max_elements\n        self._ef_construction = ef_construction\n        self._m = m\n        self._ef_search = ef_search\n        self._auto_save = auto_save\n        self._save_path = Path(save_path) if save_path else None\n","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/adapters/hnsw.py#L243-L279","documentation":"HNSWVectorIndex.__init__ checks hnswlib availability via _check_hnswlib_available() and raises this ImportError when the native package is absent or unloadable. The message warns that hnswlib needs C++ compilation and is platform-fragile — notably crashing with SIGILL on CPUs lacking AVX — because the wheel either can't be built or the binary faults at runtime on old hardware.","triggerScenarios":"Constructing HNSWVectorIndex() where hnswlib is not installed, failed to compile during install (no C++ toolchain), or was avoided deliberately on pre-AVX CPUs. Headroom treats it as an optional vector-index adapter for exactly this reason.","commonSituations":"Alpine/slim Docker images without gcc; older Xeon/desktop CPUs without AVX where the shipped wheel raises SIGILL; python versions with no prebuilt hnswlib wheel; CI environments intentionally excluding native deps.","solutions":["pip install hnswlib (with build-essential / a C++ compiler available if no wheel exists for your platform).","On pre-AVX hardware, do NOT install it — use SQLiteVectorIndex instead, which is pure-SQL and safe everywhere.","In Dockerfiles, install gcc/g++ before pip install if you must build from source.","Confirm importability first: python -c \"import hnswlib\" to separate install failure from constructor failure."],"exampleFix":"# before\nfrom headroom.memory.adapters import HNSWVectorIndex\nidx = HNSWVectorIndex(dimension=384)  # ImportError: hnswlib required\n\n# after\nfrom headroom.memory.adapters import SQLiteVectorIndex\nidx = SQLiteVectorIndex(dimension=384)  # portable fallback, no native deps","handlingStrategy":"fallback","validationCode":"def hnsw_safe() -> bool:\n    try:\n        import hnswlib  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nVectorIndex = HNSWVectorIndex if hnsw_safe() else SQLiteVectorIndex","typeGuard":null,"tryCatchPattern":"try:\n    idx = HNSWVectorIndex(dimension=dim)\nexcept ImportError as e:\n    if \"hnswlib\" in str(e):\n        idx = SQLiteVectorIndex(dimension=dim)  # documented portable fallback\n    else:\n        raise","preventionTips":["On pre-AVX CPUs, standardize on SQLiteVectorIndex; don't attempt hnswlib at all.","Ship hnswlib in the deployment image (with a C++ toolchain) rather than installing at runtime.","Gate on importability once at startup, not per request."],"tags":["dependencies","native","vector-index","hnsw","memory"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}