headroomlabs-ai/headroom · error · ValueError

save_path must be provided when auto_save is True

Error message

save_path must be provided when auto_save is True

What it means

HNSWVectorIndex.__init__ requires a save_path whenever auto_save=True, because auto_save implies persisting the index to disk after every modification and there is nowhere sensible to default that path. This ValueError fails fast before the hnswlib index is created, rather than failing later on first insert.

Source

Thrown at headroom/memory/adapters/hnsw.py:270

            max_entries: Soft limit on number of entries. When reached,
                        lowest importance entries are evicted. None = unbounded.
            eviction_batch_size: Number of entries to evict when limit is reached.

        Raises:
            ValueError: If auto_save is True but save_path is not provided.
            ImportError: If hnswlib is not installed.
        """
        if not _check_hnswlib_available():
            raise ImportError(
                "hnswlib is required for HNSWVectorIndex. "
                "Install with: pip install hnswlib\n"
                "Note: hnswlib requires C++ compilation and may not be "
                "available on all platforms (crashes with SIGILL on CPUs "
                "without AVX support)."
            )

        if auto_save and save_path is None:
            raise ValueError("save_path must be provided when auto_save is True")

        self._dimension = dimension
        self._max_elements = max_elements
        self._ef_construction = ef_construction
        self._m = m
        self._ef_search = ef_search
        self._auto_save = auto_save
        self._save_path = Path(save_path) if save_path else None

        # Memory bounding
        self._max_entries = max_entries
        self._eviction_batch_size = eviction_batch_size
        self._eviction_count = 0  # Track total evictions for stats

        # Initialize HNSW index with cosine similarity
        # hnswlib uses 'cosine' space which internally normalizes vectors
        # Note: hnswlib is guaranteed non-None here due to _check_hnswlib_available() above
        self._index = hnswlib.Index(space="cosine", dim=dimension)  # type: ignore[union-attr]

View on GitHub (pinned to 322425c43b)

Solutions

1. Provide a path: HNSWVectorIndex(dimension=384, auto_save=True, save_path="data/memory.hnsw").
2. Or drop auto_save and call save(path) explicitly at chosen checkpoints.
3. Validate config at load time: assert not (cfg['auto_save'] and not cfg.get('save_path')).
4. Ensure the directory of save_path exists and is writable to avoid the next failure after this one.

Example fix

# before
idx = HNSWVectorIndex(dimension=384, auto_save=True)  # ValueError

# after
from pathlib import Path
idx = HNSWVectorIndex(dimension=384, auto_save=True, save_path=Path("data/memory.hnsw"))

auto_save = cfg.get("auto_save", False)
save_path = cfg.get("save_path")
if auto_save and not save_path:
    raise SystemExit("config error: save_path is required when auto_save is enabled")

def valid_hnsw_config(auto_save: bool, save_path: str | None) -> bool:
    """HNSWVectorIndex accepts (auto_save=True, save_path=None) never."""
    return not auto_save or bool(save_path)

try:
    idx = HNSWVectorIndex(dimension=dim, auto_save=auto_save, save_path=save_path)
except ValueError as e:
    if "save_path must be provided" in str(e):
        idx = HNSWVectorIndex(dimension=dim, auto_save=False)  # manual save() instead
    else:
        raise

When it happens

Trigger: Constructing HNSWVectorIndex(auto_save=True) with save_path omitted — typically a config object where auto_save was flipped on but the path key was never added, or copy-pasted config between index instances that don't all need persistence.

Common situations: Enabling crash-safety in config after initially running in-memory; YAML keys save_path: vs path: mismatch; passing save_path=None explicitly from a templated config; multiple index instances sharing one config block where only some have paths.

Related errors

• bedrock_eventstream_parse_failed
• max_size must be at least 1, got {max_size}
• Unknown backend: {self._backend_type}
• bedrock_eventstream_crc_mismatch
• Unknown provider: {self.llm_config.provider}

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/f4966e43564d6757. Report an issue: GitHub.