headroomlabs-ai/headroom · error · ValueError

Invalid memory_storage_mode={config.memory_storage_mode!r};

Error message

Invalid memory_storage_mode={config.memory_storage_mode!r}; expected one of {[m.value for m in MemoryStorageMode]}

What it means

During app creation, ProxyConfig.memory_storage_mode is converted to the MemoryStorageMode enum; unknown strings raise with the list of accepted values rather than falling back. This runs immediately after memory_mode validation and gates MemoryConfig construction.

Source

Thrown at headroom/proxy/server.py:1270

            # PR-B6: translate the string-typed ``ProxyConfig.memory_mode``
            # into the typed ``MemoryMode`` enum. Unknown values raise
            # loudly per the no-silent-fallback policy.
            from headroom.proxy.memory_handler import MemoryMode

            try:
                _memory_mode = MemoryMode(config.memory_mode)
            except ValueError as exc:
                raise ValueError(
                    f"Invalid memory_mode={config.memory_mode!r}; "
                    f"expected one of {[m.value for m in MemoryMode]}"
                ) from exc

            from headroom.memory.storage_router import MemoryStorageMode

            try:
                _storage_mode = MemoryStorageMode(config.memory_storage_mode)
            except ValueError as exc:
                raise ValueError(
                    f"Invalid memory_storage_mode={config.memory_storage_mode!r}; "
                    f"expected one of {[m.value for m in MemoryStorageMode]}"
                ) from exc

            memory_config = MemoryConfig(
                enabled=True,
                backend=config.memory_backend,
                db_path=_mem_db_path,
                inject_tools=config.memory_inject_tools,
                use_native_tool=config.memory_use_native_tool,
                inject_context=config.memory_inject_context,
                top_k=config.memory_top_k,
                min_similarity=config.memory_min_similarity,
                mode=_memory_mode,
                storage_mode=_storage_mode,
                project_root_override=config.memory_project_root_override,
                qdrant_url=config.memory_qdrant_url,
                qdrant_host=config.memory_qdrant_host,

View on GitHub (pinned to 322425c43b)

Solutions

1. Use one of the values printed in the error exactly.
2. Drop the memory_storage_mode key to fall back to its supported default.
3. After upgrading headroom, validate all memory_* keys against current enums.

Example fix

# before
ProxyConfig(memory_storage_mode="sqlite_only")

# after
from headroom.memory.storage_router import MemoryStorageMode
ProxyConfig(memory_storage_mode=MemoryStorageMode.SQLITE.value)  # use a listed value

from headroom.memory.storage_router import MemoryStorageMode
if cfg["memory_storage_mode"] not in {m.value for m in MemoryStorageMode}:
    raise SystemExit(f"must be one of {[m.value for m in MemoryStorageMode]}")

from headroom.memory.storage_router import MemoryStorageMode
def is_storage_mode(v: str) -> bool:
    return v in {m.value for m in MemoryStorageMode}

try:
    app = create_app(config)
except ValueError as e:
    if "memory_storage_mode" in str(e):
        fix_config(e)
    raise

When it happens

Trigger: ProxyConfig(memory_storage_mode='sqlite_only') or any string not in MemoryStorageMode; commonly a typo, case mismatch, or version-skewed value.

Common situations: Old configs referencing renamed storage backends; documentation drift between releases; direct JSON config use.

Related errors

• Invalid memory_mode={config.memory_mode!r}; expected one of
• Unknown provider: {self.provider}
• api_key is required for cloud mode
• default_importance must be 0.0-1.0, got {self.default_import
• dedup_similarity_threshold must be 0.0-1.0, got {self.dedup_

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