{"record":{"id":"209de7bcac0b8cf6","repo":"langchain-ai/deepagents","slug":"backend-must-be-an-initialized-backend-instance-b","errorCode":null,"errorMessage":"backend must be an initialized backend instance. Backend factories were removed in deepagents 0.7; pass StateBackend(), CompositeBackend(...), or another BackendProtocol instance instead.","messagePattern":"backend must be an initialized backend instance\\. Backend factories were removed in deepagents 0\\.7; pass StateBackend\\(\\), CompositeBackend\\(\\.\\.\\.\\), or another BackendProtocol instance instead\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/middleware/filesystem.py","lineNumber":1712,"sourceCode":"        \"\"\"\n        if isinstance(tools, list) and \"read_file\" not in tools:\n            msg = \"read_file must be included in tools; it is required by FilesystemMiddleware\"\n            raise ValueError(msg)\n        if max_execute_timeout <= 0:\n            msg = f\"max_execute_timeout must be positive, got {max_execute_timeout}\"\n            raise ValueError(msg)\n        if grep_max_count is not None and grep_max_count <= 0:\n            msg = f\"grep_max_count must be positive or None, got {grep_max_count}\"\n            raise ValueError(msg)\n        # Use provided backend or default to StateBackend instance\n        self.backend = backend if backend is not None else StateBackend()\n        if callable(self.backend) and not isinstance(self.backend, BackendProtocol):\n            msg = (\n                \"backend must be an initialized backend instance. Backend factories \"\n                \"were removed in deepagents 0.7; pass StateBackend(), \"\n                \"CompositeBackend(...), or another BackendProtocol instance instead.\"\n            )\n            raise TypeError(msg)\n        self.state_schema = cast(\n            \"type[FilesystemState]\",\n            FilesystemState if _uses_state_backend(self.backend) else AgentState,\n        )\n        if _permissions and supports_execution(self.backend) and not _all_paths_scoped_to_routes(_permissions, self.backend):\n            msg = (\n                \"FilesystemMiddleware does not yet support permissions with backends that \"\n                \"provide command execution (SandboxBackendProtocol). Tool-level permissions \"\n                \"for the execute tool are not implemented. Either remove permissions or use \"\n                \"a backend without execution support.\"\n            )\n            raise NotImplementedError(msg)\n\n        artifacts_root = self.backend.artifacts_root if isinstance(self.backend, CompositeBackend) else \"/\"\n        _root = artifacts_root.rstrip(\"/\")\n        self._large_tool_results_prefix = f\"{_root}/large_tool_results\"\n        self._conversation_history_prefix = f\"{_root}/conversation_history\"\n","sourceCodeStart":1694,"sourceCodeEnd":1730,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/middleware/filesystem.py#L1694-L1730","documentation":"FilesystemMiddleware's `backend` parameter must be an initialized BackendProtocol instance. Passing a callable (a backend factory) raises TypeError because factory support was removed in deepagents 0.7; backends must now be instantiated before being handed to the middleware.","triggerScenarios":"Passing a callable that is not a BackendProtocol instance, e.g. FilesystemMiddleware(backend=SandboxBackend) (the class itself) or backend=lambda: StateBackend(), or passing a legacy factory function from pre-0.7 code.","commonSituations":"Upgrading from deepagents < 0.7 where backend factories were supported; docs/examples or internal code that passed backend classes or factory functions instead of instances.","solutions":["Instantiate the backend: pass StateBackend() instead of StateBackend","Replace any legacy factory with CompositeBackend(...) or another BackendProtocol instance constructed eagerly","Check the deepagents 0.7 migration notes for removed factory APIs"],"exampleFix":"// before\nmw = FilesystemMiddleware(backend=StateBackend)\n// after\nmw = FilesystemMiddleware(backend=StateBackend())","handlingStrategy":"type-guard","validationCode":"def check_backend(b):\n    if callable(b) and not isinstance(b, BackendProtocol):\n        raise TypeError(\"backend must be an initialized BackendProtocol instance (factories removed in 0.7)\")\n    return b","typeGuard":"def is_backend_instance(b) -> bool:\n    return not callable(b) or isinstance(b, BackendProtocol)","tryCatchPattern":"try:\n    mw = FilesystemMiddleware(backend=maybe_backend)\nexcept TypeError as e:\n    if \"Backend factories were removed\" in str(e):\n        maybe_backend = maybe_backend()  # migrate: instantiate the factory\n        mw = FilesystemMiddleware(backend=maybe_backend)\n    else:\n        raise","preventionTips":["After upgrading to deepagents 0.7, grep for `backend=` usages and ensure instances are passed","Never pass backend classes or lambdas; always construct eagerly","Pin the version in CI and run the 0.7 migration checklist"],"tags":["python","breaking-change","backend","migration"],"backgroundTag":"backend-factory-removed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}