headroomlabs-ai/headroom · error · ValueError

vector_dimension must be positive, got {self.vector_dimensio

Error message

vector_dimension must be positive, got {self.vector_dimension}

What it means

ValueError raised in MemoryConfig.__post_init__ (vector memory system config) when vector_dimension < 1. The vector_dimension must match the embedder's output size (e.g. 1536 for OpenAI text-embedding-3-small) and index stores keyed on it, so zero/negative dimensions are rejected at construction.

Source

Thrown at headroom/memory/config.py:137

    # Embedder
    embedder_backend: EmbedderBackend = EmbedderBackend.LOCAL
    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")

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the dimension to your embedder's output size: 1536 for text-embedding-3-small, 3072 for -large, 384 for all-MiniLM-L6-v2
2. Fail loudly at config load time if the env var is empty rather than coercing to 0
3. If unsure, check len(embedding) from one sample embed call

Example fix

# before
cfg = MemoryConfig(vector_dimension=0)  # ValueError: vector_dimension must be positive

# after
cfg = MemoryConfig(vector_dimension=1536)  # match your embedder

def check_dimension(dim: int) -> int:
    if dim < 1:
        raise ValueError(f'vector_dimension must be >= 1, got {dim}')
    return dim

dim = int(os.environ.get('VECTOR_DIMENSION') or 1536)  # never default to 0
cfg = MemoryConfig(vector_dimension=check_dimension(dim))

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

try:
    cfg = MemoryConfig(vector_dimension=dim)
except ValueError as e:
    raise SystemExit(f'Bad memory config: {e}') from e

When it happens

Trigger: MemoryConfig(vector_dimension=0) or a negative value, typically from an env var defaulting to 0 or a config template placeholder never filled in.

Common situations: Optional config left as 0 meaning 'unset'; .env with VECTOR_DIMENSION= for later override that never happens; switching embedders without updating the dimension.

Related errors

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

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