{"record":{"id":"4ca9fde24db9abf1","repo":"bytedance/deer-flow","slug":"memory-manager-class-manager-class-r-is-not-a-re","errorCode":null,"errorMessage":"memory.manager_class={manager_class!r} is not a registered backend name (known: {sorted(registry)}) nor a resolvable 'pkg.mod:Cls' path{dotted_error_suffix}. Fix memory.manager_class in config; refusing to silently fall back to a different storage backend (memory is persistent state -- a wrong store is a silent data-integrity footgun).","messagePattern":"memory\\.manager_class=(.+?) is not a registered backend name \\(known: (.+?)\\) nor a resolvable 'pkg\\.mod:Cls' path(.+?)\\. Fix memory\\.manager_class in config; refusing to silently fall back to a different storage backend \\(memory is persistent state -- a wrong store is a silent data-integrity footgun\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"backend/packages/harness/deerflow/agents/memory/manager.py","lineNumber":602,"sourceCode":"    if \":\" in manager_class:\n        module_path, _, attr = manager_class.partition(\":\")\n    else:\n        module_path, _, attr = manager_class.rpartition(\".\")\n    if module_path and attr:\n        try:\n            module = importlib.import_module(module_path)\n        except ImportError as e:\n            dotted_error = f\"cannot import module {module_path!r}: {e}\"\n        else:\n            cls = getattr(module, attr, None)\n            if cls is None:\n                dotted_error = f\"attribute {attr!r} not found in {module_path!r}\"\n            elif not (isinstance(cls, type) and issubclass(cls, MemoryManager)):\n                dotted_error = f\"{manager_class!r} resolved to non-MemoryManager {cls!r}\"\n            else:\n                return cls\n\n    raise ValueError(\n        f\"memory.manager_class={manager_class!r} is not a registered backend name \"\n        f\"(known: {sorted(registry)}) nor a resolvable 'pkg.mod:Cls' path\" + (f\": {dotted_error}\" if dotted_error else \"\") + \". Fix memory.manager_class in config; refusing to silently fall back to a \"\n        \"different storage backend (memory is persistent state -- a wrong store is a \"\n        \"silent data-integrity footgun).\"\n    )\n\n\ndef backend_requires_passive_writes_in_tool_mode(manager_class: str) -> bool:\n    \"\"\"Return whether a backend needs middleware writes in tool mode.\n\n    Resolve the class without constructing it so agent assembly does not run\n    backend startup checks or perform network I/O.\n    \"\"\"\n    return _resolve_manager_class(manager_class).requires_passive_writes_in_tool_mode\n\n\n# ── Host-default hook providers (passed to from_config by the factory) ────\n#","sourceCodeStart":584,"sourceCodeEnd":620,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/packages/harness/deerflow/agents/memory/manager.py#L584-L620","documentation":"This ValueError is a deliberate fail-fast config guard in _resolve_manager_class (deerflow/agents/memory/manager.py:602). A memory.manager_class value is resolved either as a registered short name (backends discovered under deerflow/agents/memory/backends/ exposing MANAGER_CLASS: deermem, honcho, mem0, noop, openviking) or as a dotted 'pkg.mod:Cls' / 'pkg.mod.Cls' import path that must land on a MemoryManager subclass. If neither works, the factory refuses to start rather than silently substituting a different store, because memory is persistent state and routing writes to the wrong backend would be a silent data-integrity footgun. The manager is resolved eagerly at Gateway startup so the operator sees this immediately.","triggerScenarios":"Setting memory.manager_class in config.yaml to a misspelled backend name (e.g. 'deerMem', 'mem-0'), to an uninstalled optional backend package (mem0/honcho/openviking extras not installed, so the backend directory is absent from the registry), or to a dotted path whose module cannot be imported, whose attribute is missing, or whose target class is not a MemoryManager subclass. The error is raised at startup, on first agent assembly, or on any config reload that re-resolves the manager.","commonSituations":"Typo in memory.manager_class while enabling a remote backend; copying a config.yaml that references a custom in-house backend class not present in the new deployment; optional backend extras not installed (pip install without the backend extra), so a known name is missing from the registry; a dotted path referencing a class that refactored or moved between DeerFlow versions.","solutions":["Read the message: it lists the known registry names — correct memory.manager_class to one of them exactly (case-sensitive: deermem, honcho, mem0, noop, openviking).","If a dotted path was intended, verify the module imports and the attribute exists and is a MemoryManager subclass; use the 'pkg.mod:Cls' form.","Install the optional backend dependency/extras so the backend package is discoverable under deerflow/agents/memory/backends/.","For custom backends, confirm the package directory exposes MANAGER_CLASS = YourManager (a MemoryManager subclass) in its __init__.py.","Restart the Gateway after fixing config.yaml — the value is resolved eagerly at startup."],"exampleFix":"# config.yaml — before\nmemory:\n  manager_class: deerMem   # typo: not in registry (deermem, honcho, mem0, noop, openviking)\n\n# config.yaml — after\nmemory:\n  manager_class: deermem","handlingStrategy":"validation","validationCode":"from deerflow.agents.memory.manager import _resolve_manager_class, MemoryManager\n\ndef validate_manager_class(name: str) -> None:\n    \"\"\"Fail in CI/preflight instead of at Gateway startup.\"\"\"\n    try:\n        cls = _resolve_manager_class(name)\n    except ValueError as e:\n        raise SystemExit(f\"config error: {e}\") from e\n    assert issubclass(cls, MemoryManager)","typeGuard":null,"tryCatchPattern":"try:\n    cls = _resolve_manager_class(config.memory.manager_class)\nexcept ValueError as e:\n    # config error: fail startup loudly with the message (it lists known backends)\n    raise RuntimeError(str(e)) from e","preventionTips":["Run a config preflight (make doctor / explicit _resolve_manager_class check) before deploying a changed config.yaml.","Copy manager_class values verbatim from the registry names printed in backend/AGENTS.md or the error message; they are case-sensitive.","Install optional backend extras in the same change that switches manager_class to them.","For custom dotted-path backends, add a smoke test that imports and subclass-checks the target class in CI."],"tags":["memory","configuration","startup","backend","deerflow"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}