headroomlabs-ai/headroom · error · ValueError

hnsw_ef_search must be positive, got {self.hnsw_ef_search}

Error message

hnsw_ef_search must be positive, got {self.hnsw_ef_search}

What it means

ValueError raised in MemoryConfig.__post_init__ when hnsw_ef_search < 1. ef_search controls the HNSW query-time candidate list size — the recall/speed tradeoff knob — and must be at least 1 for search to visit any nodes. Validation happens at construction, before the index is used.

Source

Thrown at headroom/memory/config.py:148

    # 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. Set a positive value (typical range 16-256; higher = better recall, slower search) or omit for the default
2. Map missing/0 config inputs to the default instead of passing them through
3. Profile with a valid ef_search rather than 0 when tuning latency

Example fix

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

# after
cfg = MemoryConfig(hnsw_ef_search=64)

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_search=positive_int('hnsw_ef_search', 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_search=raw_ef)
except ValueError:
    cfg = MemoryConfig()  # defaults

When it happens

Trigger: MemoryConfig(hnsw_ef_search=0) or negative; often an attempt to 'disable' the parameter or a value sourced from an empty env var defaulted to 0.

Common situations: Operators setting 0 expecting default behavior; configs generated from templates with unfilled numeric placeholders; latency tuning gone wrong.

Related errors

• hnsw_ef_construction must be positive, got {self.hnsw_ef_con
• hnsw_m must be positive, got {self.hnsw_m}
• 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/5323cb50ccfa6271. Report an issue: GitHub.