headroomlabs-ai/headroom · error · ValueError

Invalid memory_mode={config.memory_mode!r}; expected one of

Error message

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

What it means

During app creation, the string-typed ProxyConfig.memory_mode is converted to the MemoryMode enum, and unknown strings raise loudly instead of silently falling back. The error lists the accepted enum values. It occurs after memory directories are prepared, before MemoryConfig is built.

Source

Thrown at headroom/proxy/server.py:1260

            )
        elif config.memory_enabled:
            # Resolve memory DB path: empty → project-scoped default
            _mem_db_path = config.memory_db_path
            if not _mem_db_path:
                _mem_dir = Path.cwd() / ".headroom"
                _mem_dir.mkdir(parents=True, exist_ok=True)
                _mem_db_path = str(_mem_dir / "memory.db")
                logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")

            # 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,

View on GitHub (pinned to 322425c43b)

Solutions

1. Check the error's accepted-values list and use an exact enum value.
2. Update or remove the memory_mode key so a supported default applies.
3. Regenerate config files after upgrading headroom.

Example fix

# before
config = ProxyConfig(memory_mode="aggressive")

# after
from headroom.proxy.memory_handler import MemoryMode
config = ProxyConfig(memory_mode=MemoryMode.SESSION.value)  # use a listed value

from headroom.proxy.memory_handler import MemoryMode
if cfg["memory_mode"] not in {m.value for m in MemoryMode}:
    raise SystemExit(f"memory_mode must be one of {[m.value for m in MemoryMode]}")

from headroom.proxy.memory_handler import MemoryMode
def is_memory_mode(v: str) -> bool:
    return v in {m.value for m in MemoryMode}

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

When it happens

Trigger: ProxyConfig(memory_mode='aggressive') or any value not in MemoryMode, supplied via config file or programmatic construction; usually a typo or a value from an older/newer version.

Common situations: Version skew between config and installed headroom; hand-edited YAML/JSON with a stale mode name; case-sensitive value like 'Session'.

Related errors

• Invalid memory_storage_mode={config.memory_storage_mode!r};
• 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/93fe0adf96db71f2. Report an issue: GitHub.