bytedance/deer-flow · critical · ValueError

backend_config.storage_class={storage_class_path!r} failed t

Error message

backend_config.storage_class={storage_class_path!r} failed to load: {exc}. Refusing to silently fall back because memory is persistent state.

What it means

create_storage() loads config.storage_class as a dotted 'module:ClassName' path and instantiates it as the MemoryStorage. Every failure - import error, missing attribute, wrong type (not a MemoryStorage subclass), or constructor exception - is wrapped in this ValueError. The message is explicit that there is no silent fallback to file storage because memory is persistent state: a typo must crash, not quietly re-root your memory directory.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:1548

                factory = create_fts5_retrieval
            else:
                module_path, factory_name = config.retrieval_adapter.rsplit(".", 1)
                factory = getattr(importlib.import_module(module_path), factory_name)
            retrieval = factory(config)
        except Exception as exc:
            raise ValueError(f"backend_config.retrieval_adapter={config.retrieval_adapter!r} failed to load: {exc}") from exc
    storage_class_path = config.storage_class
    if not storage_class_path or storage_class_path == "file":
        return FileMemoryStorage(config, retrieval=retrieval)
    try:
        module_path, class_name = storage_class_path.rsplit(".", 1)
        storage_class = getattr(importlib.import_module(module_path), class_name)
        if not isinstance(storage_class, type) or not issubclass(storage_class, MemoryStorage):
            raise TypeError(f"Configured memory storage '{storage_class_path}' is not a MemoryStorage class")
        return storage_class(config)
    except Exception as exc:
        raise ValueError(f"backend_config.storage_class={storage_class_path!r} failed to load: {exc}. Refusing to silently fall back because memory is persistent state.") from exc

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check __cause__ in the traceback for the underlying ImportError/TypeError/constructor error.
2. Verify the class is importable in the exact runtime env: python -c "from myapp.storage import PostgresMemoryStorage" inside the backend environment.
3. Ensure the class subclasses MemoryStorage and accepts DeerMemConfig as its first constructor argument.
4. To use the built-in file storage, set storage_class to 'file' or leave it empty - do not point it at a broken class.

Example fix

# before (config.yaml)
backend_config:
  storage_class: "myapp.storage.PostgresMemoryStorage"  # module path wrong

# after
backend_config:
  storage_class: "myapp.memory.storage:PostgresMemoryStorage"

def storage_class_loads(path: str) -> bool:
    try:
        module_path, class_name = path.rsplit(".", 1)
        cls = getattr(importlib.import_module(module_path), class_name)
        return isinstance(cls, type) and issubclass(cls, MemoryStorage)
    except Exception:
        return False

try:
    storage = create_storage(config)
except ValueError as exc:
    if "storage_class" in str(exc):
        # fail fast at startup with the underlying cause; do NOT fall back to file storage
        raise RuntimeError(f"Refusing to start with broken memory storage: {exc.__cause__}") from exc
    raise

When it happens

Trigger: backend_config.storage_class: 'myapp.storage:PostgresMemoryStorage' where the module is not installed in the Gateway env, the class does not subclass MemoryStorage, or its __init__ raises on the provided config (bad DSN, unreachable DB).

Common situations: Deploying with a custom storage plugin but forgetting to install it into the service environment; renaming the class; plugin API changes after upgrade; constructor env vars (DB URL) missing in production.

Related errors

• backend_config.retrieval_adapter={config.retrieval_adapter!r
• DeerMem memory update requested but no LLM is configured (se
• Fact was not stored because memory.max_facts kept higher-con
• Missing or empty 'messages' key in {path}
• chat prompt template not found: {name} (searched: {searched}

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