{"record":{"id":"0e3260f6729cc96f","repo":"bytedance/deer-flow","slug":"backend-config-storage-class-storage-class-path-r","errorCode":null,"errorMessage":"backend_config.storage_class={storage_class_path!r} failed to load: {exc}. Refusing to silently fall back because memory is persistent state.","messagePattern":"backend_config\\.storage_class=(.+?) failed to load: (.+?)\\. Refusing to silently fall back because memory is persistent state\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py","lineNumber":1548,"sourceCode":"\n                factory = create_fts5_retrieval\n            else:\n                module_path, factory_name = config.retrieval_adapter.rsplit(\".\", 1)\n                factory = getattr(importlib.import_module(module_path), factory_name)\n            retrieval = factory(config)\n        except Exception as exc:\n            raise ValueError(f\"backend_config.retrieval_adapter={config.retrieval_adapter!r} failed to load: {exc}\") from exc\n    storage_class_path = config.storage_class\n    if not storage_class_path or storage_class_path == \"file\":\n        return FileMemoryStorage(config, retrieval=retrieval)\n    try:\n        module_path, class_name = storage_class_path.rsplit(\".\", 1)\n        storage_class = getattr(importlib.import_module(module_path), class_name)\n        if not isinstance(storage_class, type) or not issubclass(storage_class, MemoryStorage):\n            raise TypeError(f\"Configured memory storage '{storage_class_path}' is not a MemoryStorage class\")\n        return storage_class(config)\n    except Exception as exc:\n        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\n","sourceCodeStart":1530,"sourceCodeEnd":1549,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py#L1530-L1549","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check __cause__ in the traceback for the underlying ImportError/TypeError/constructor error.","Verify the class is importable in the exact runtime env: python -c \"from myapp.storage import PostgresMemoryStorage\" inside the backend environment.","Ensure the class subclasses MemoryStorage and accepts DeerMemConfig as its first constructor argument.","To use the built-in file storage, set storage_class to 'file' or leave it empty - do not point it at a broken class."],"exampleFix":"# before (config.yaml)\nbackend_config:\n  storage_class: \"myapp.storage.PostgresMemoryStorage\"  # module path wrong\n\n# after\nbackend_config:\n  storage_class: \"myapp.memory.storage:PostgresMemoryStorage\"","handlingStrategy":"try-catch","validationCode":"def storage_class_loads(path: str) -> bool:\n    try:\n        module_path, class_name = path.rsplit(\".\", 1)\n        cls = getattr(importlib.import_module(module_path), class_name)\n        return isinstance(cls, type) and issubclass(cls, MemoryStorage)\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    storage = create_storage(config)\nexcept ValueError as exc:\n    if \"storage_class\" in str(exc):\n        # fail fast at startup with the underlying cause; do NOT fall back to file storage\n        raise RuntimeError(f\"Refusing to start with broken memory storage: {exc.__cause__}\") from exc\n    raise","preventionTips":["Never add a silent file-storage fallback around create_storage - the library refuses it on purpose.","Add a startup health check that imports and instantiates the storage class with the real config.","Include custom storage plugins in deployment dependencies and CI."],"tags":["memory","configuration","dynamic-import","fail-fast","deermem"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}