headroomlabs-ai/headroom · error · ValueError

hnsw_ef_construction must be positive, got {self.hnsw_ef_con

Error message

hnsw_ef_construction must be positive, got {self.hnsw_ef_construction}

What it means

ValueError raised in MemoryConfig.__post_init__ when hnsw_ef_construction < 1. This parameter controls the HNSW index build quality (ef_construction); zero or negative values are invalid for the underlying ANN index and are rejected before any data is written.

Source

Thrown at headroom/memory/config.py:140

    embedder_model: str = field(default_factory=lambda: ML_MODEL_DEFAULTS.sentence_transformer)
    openai_api_key: str | None = None
    ollama_base_url: str = "http://localhost:11434"

    # Cache
    cache_enabled: bool = True
    cache_max_size: int = 1000

    # Bubbling defaults
    auto_bubble: bool = True
    bubble_threshold: float = 0.7  # Minimum importance for bubbling

    def __post_init__(self) -> None:
        """Validate configuration after initialization."""
        if self.vector_dimension < 1:
            raise ValueError(f"vector_dimension must be positive, got {self.vector_dimension}")

        if self.hnsw_ef_construction < 1:
            raise ValueError(
                f"hnsw_ef_construction must be positive, got {self.hnsw_ef_construction}"
            )

        if self.hnsw_m < 1:
            raise ValueError(f"hnsw_m must be positive, got {self.hnsw_m}")

        if self.hnsw_ef_search < 1:
            raise ValueError(f"hnsw_ef_search must be positive, got {self.hnsw_ef_search}")

        if self.cache_max_size < 1:
            raise ValueError(f"cache_max_size must be positive, got {self.cache_max_size}")

        if self.embedder_backend == EmbedderBackend.OPENAI and not self.openai_api_key:
            raise ValueError("openai_api_key is required when using OpenAI embedder backend")

        # Ensure db_path is a Path object
        if isinstance(self.db_path, str):
            self.db_path = Path(self.db_path)

View on GitHub (pinned to 322425c43b)

Solutions

1. Use a positive value; sane ranges are 100-500 (omit the field entirely to use the default)
2. Validate parsed numeric config before constructing MemoryConfig so 0/empty fails with context
3. Leave HNSW build params at defaults unless you have a measured reason to tune

Example fix

# before
cfg = MemoryConfig(hnsw_ef_construction=0)  # ValueError

# after
cfg = MemoryConfig()  # defaults
cfg = MemoryConfig(hnsw_ef_construction=200)  # or explicit positive tuning

def positive_int(name: str, v: int) -> int:
    if v < 1:
        raise ValueError(f'{name} must be >= 1, got {v}')
    return v

cfg = MemoryConfig(hnsw_ef_construction=positive_int('hnsw_ef_construction', raw_ef))

def is_positive_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

try:
    cfg = MemoryConfig(hnsw_ef_construction=raw_ef)
except ValueError:
    cfg = MemoryConfig()  # defaults

When it happens

Trigger: MemoryConfig(hnsw_ef_construction=0) or negative — usually a misread config where the operator meant to use the default and set 0, or a value loaded from an unset env var.

Common situations: '0 means default' conventions from other systems; tuning configs copied from docs with different parameter names; disabling-tuning attempts.

Related errors

• hnsw_m must be positive, got {self.hnsw_m}
• hnsw_ef_search must be positive, got {self.hnsw_ef_search}
• default_importance must be 0.0-1.0, got {self.default_import
• dedup_similarity_threshold must be 0.0-1.0, got {self.dedup_
• vector_dimension must be positive, got {self.vector_dimensio

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