bytedance/deer-flow · critical · ValueError

memory.manager_class={manager_class!r} is not a registered b

Error message

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).

What it means

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.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/manager.py:602

    if ":" in manager_class:
        module_path, _, attr = manager_class.partition(":")
    else:
        module_path, _, attr = manager_class.rpartition(".")
    if module_path and attr:
        try:
            module = importlib.import_module(module_path)
        except ImportError as e:
            dotted_error = f"cannot import module {module_path!r}: {e}"
        else:
            cls = getattr(module, attr, None)
            if cls is None:
                dotted_error = f"attribute {attr!r} not found in {module_path!r}"
            elif not (isinstance(cls, type) and issubclass(cls, MemoryManager)):
                dotted_error = f"{manager_class!r} resolved to non-MemoryManager {cls!r}"
            else:
                return cls

    raise ValueError(
        f"memory.manager_class={manager_class!r} is not a registered backend name "
        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 "
        "different storage backend (memory is persistent state -- a wrong store is a "
        "silent data-integrity footgun)."
    )


def backend_requires_passive_writes_in_tool_mode(manager_class: str) -> bool:
    """Return whether a backend needs middleware writes in tool mode.

    Resolve the class without constructing it so agent assembly does not run
    backend startup checks or perform network I/O.
    """
    return _resolve_manager_class(manager_class).requires_passive_writes_in_tool_mode


# ── Host-default hook providers (passed to from_config by the factory) ────
#

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. 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).
2. 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.
3. Install the optional backend dependency/extras so the backend package is discoverable under deerflow/agents/memory/backends/.
4. For custom backends, confirm the package directory exposes MANAGER_CLASS = YourManager (a MemoryManager subclass) in its __init__.py.
5. Restart the Gateway after fixing config.yaml — the value is resolved eagerly at startup.

Example fix

# config.yaml — before
memory:
  manager_class: deerMem   # typo: not in registry (deermem, honcho, mem0, noop, openviking)

# config.yaml — after
memory:
  manager_class: deermem

from deerflow.agents.memory.manager import _resolve_manager_class, MemoryManager

def validate_manager_class(name: str) -> None:
    """Fail in CI/preflight instead of at Gateway startup."""
    try:
        cls = _resolve_manager_class(name)
    except ValueError as e:
        raise SystemExit(f"config error: {e}") from e
    assert issubclass(cls, MemoryManager)

try:
    cls = _resolve_manager_class(config.memory.manager_class)
except ValueError as e:
    # config error: fail startup loudly with the message (it lists known backends)
    raise RuntimeError(str(e)) from e

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DeerMem memory update requested but no LLM is configured (se
• import_memory not supported by {type(self).__name__}
• Fact was not stored because memory.max_facts kept higher-con
• backend_config.retrieval_adapter={config.retrieval_adapter!r
• backend_config.storage_class={storage_class_path!r} failed t

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/4ca9fde24db9abf1. Report an issue: GitHub.