{"record":{"id":"bcb94d19804fe7c5","repo":"headroomlabs-ai/headroom","slug":"unknown-backend-self-backend-type","errorCode":null,"errorMessage":"Unknown backend: {self._backend_type}","messagePattern":"Unknown backend: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/memory/easy.py","lineNumber":186,"sourceCode":"                mem0_config = Mem0Config(\n                    qdrant_url=self._qdrant_url,\n                    qdrant_host=self._qdrant_host,\n                    qdrant_port=self._qdrant_port,\n                    qdrant_api_key=self._qdrant_api_key,\n                    neo4j_uri=self._neo4j_uri,\n                    neo4j_user=self._neo4j_user,\n                    neo4j_password=self._neo4j_password,\n                    enable_graph=True,\n                )\n                self._backend = DirectMem0Adapter(mem0_config)\n            except ImportError as e:\n                raise ImportError(\n                    \"qdrant-neo4j backend requires additional packages. \"\n                    \"Install with: pip install 'headroom-ai[memory-stack]'\\n\"\n                    \"And start Docker services: docker compose up -d qdrant neo4j\"\n                ) from e\n        else:\n            raise ValueError(f\"Unknown backend: {self._backend_type}\")\n\n        self._initialized = True\n\n    async def save(\n        self,\n        content: str,\n        user_id: str,\n        importance: float = 0.5,\n        facts: list[str] | None = None,\n        entities: list[dict[str, str]] | None = None,\n        relationships: list[dict[str, str]] | None = None,\n        metadata: dict[str, Any] | None = None,\n    ) -> str:\n        \"\"\"Save a memory.\n\n        Args:\n            content: The memory content to save.\n            user_id: User identifier for scoping memories.","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/easy.py#L168-L204","documentation":"The high-level Memory facade only recognizes two backend names: \"local\" and \"qdrant-neo4j\". Any other string passed as the `backend` argument reaches the final else branch in `_ensure_initialized` and raises ValueError. Initialization is lazy, so the error surfaces on the first save/search/delete/clear call, not at construction.","triggerScenarios":"Calling `Memory(backend=\"sqlite\")`, `Memory(backend=\"mem0\")`, `Memory(backend=\"qdrant\")`, or passing a typo'd/None-coerced string, then awaiting any method (e.g. `await memory.save(...)`). Constructor succeeds silently; the first backend operation raises.","commonSituations":"Developers guess backend names from the ecosystem (mem0, qdrant, neo4j, sqlite) instead of the two supported literals; passing a StoreBackend enum value meant for MemoryConfig into the easy facade; version drift after backend names were renamed in an upgrade.","solutions":["Use backend=\"local\" for the SQLite-backed local memory (default) or backend=\"qdrant-neo4j\" for the mem0 Qdrant+Neo4j stack","If you need a custom/external backend, use the lower-level factory (headroom.memory.factory.create_memory_system) with StoreBackend.EXTERNAL and an entry-point name instead of the Memory facade","Check the installed version's Memory docstring (help(Memory)) to confirm supported backend literals","Fail fast: call `await memory._ensure_initialized()` or a trivial operation right after construction to surface config errors at startup"],"exampleFix":"# before\nmemory = Memory(backend=\"mem0\")\nid = await memory.save(\"note\", user_id=\"alice\")  # ValueError: Unknown backend: mem0\n\n# after\nmemory = Memory(backend=\"qdrant-neo4j\",\n                 qdrant_url=\"https://xyz.cloud.qdrant.io:6333\",\n                 qdrant_api_key=\"...\")\nid = await memory.save(\"note\", user_id=\"alice\")","handlingStrategy":"validation","validationCode":"SUPPORTED = {\"local\", \"qdrant-neo4j\"}\nif memory_backend not in SUPPORTED:\n    raise ValueError(f\"backend must be one of {sorted(SUPPORTED)}, got {memory_backend!r}\")\nmemory = Memory(backend=memory_backend)","typeGuard":"def is_memory_backend(v: str) -> bool:\n    return v in {\"local\", \"qdrant-neo4j\"}","tryCatchPattern":"try:\n    await memory.save(content, user_id=uid)\nexcept ValueError as e:\n    if \"Unknown backend\" in str(e):\n        raise ConfigError(f\"fix Memory(backend=...): {e}\") from e\n    raise","preventionTips":["Validate the backend string at config load, not at first memory operation","Smoke-test Memory right after construction (e.g. await a cheap search) so backend errors fail at startup","Keep backend names in one constant instead of scattering string literals"],"tags":["memory","configuration","validation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}