langchain-ai/deepagents · error · TypeError

backend must be an initialized backend instance. Backend fac

Error message

backend must be an initialized backend instance. Backend factories were removed in deepagents 0.7; pass StateBackend(), CompositeBackend(...), or another BackendProtocol instance instead.

What it means

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.

Source

Thrown at libs/deepagents/deepagents/middleware/filesystem.py:1712

        """
        if isinstance(tools, list) and "read_file" not in tools:
            msg = "read_file must be included in tools; it is required by FilesystemMiddleware"
            raise ValueError(msg)
        if max_execute_timeout <= 0:
            msg = f"max_execute_timeout must be positive, got {max_execute_timeout}"
            raise ValueError(msg)
        if grep_max_count is not None and grep_max_count <= 0:
            msg = f"grep_max_count must be positive or None, got {grep_max_count}"
            raise ValueError(msg)
        # Use provided backend or default to StateBackend instance
        self.backend = backend if backend is not None else StateBackend()
        if callable(self.backend) and not isinstance(self.backend, BackendProtocol):
            msg = (
                "backend must be an initialized backend instance. Backend factories "
                "were removed in deepagents 0.7; pass StateBackend(), "
                "CompositeBackend(...), or another BackendProtocol instance instead."
            )
            raise TypeError(msg)
        self.state_schema = cast(
            "type[FilesystemState]",
            FilesystemState if _uses_state_backend(self.backend) else AgentState,
        )
        if _permissions and supports_execution(self.backend) and not _all_paths_scoped_to_routes(_permissions, self.backend):
            msg = (
                "FilesystemMiddleware does not yet support permissions with backends that "
                "provide command execution (SandboxBackendProtocol). Tool-level permissions "
                "for the execute tool are not implemented. Either remove permissions or use "
                "a backend without execution support."
            )
            raise NotImplementedError(msg)

        artifacts_root = self.backend.artifacts_root if isinstance(self.backend, CompositeBackend) else "/"
        _root = artifacts_root.rstrip("/")
        self._large_tool_results_prefix = f"{_root}/large_tool_results"
        self._conversation_history_prefix = f"{_root}/conversation_history"

View on GitHub (pinned to a1af029e6e)

Solutions

1. Instantiate the backend: pass StateBackend() instead of StateBackend
2. Replace any legacy factory with CompositeBackend(...) or another BackendProtocol instance constructed eagerly
3. Check the deepagents 0.7 migration notes for removed factory APIs

Example fix

// before
mw = FilesystemMiddleware(backend=StateBackend)
// after
mw = FilesystemMiddleware(backend=StateBackend())

def check_backend(b):
    if callable(b) and not isinstance(b, BackendProtocol):
        raise TypeError("backend must be an initialized BackendProtocol instance (factories removed in 0.7)")
    return b

def is_backend_instance(b) -> bool:
    return not callable(b) or isinstance(b, BackendProtocol)

try:
    mw = FilesystemMiddleware(backend=maybe_backend)
except TypeError as e:
    if "Backend factories were removed" in str(e):
        maybe_backend = maybe_backend()  # migrate: instantiate the factory
        mw = FilesystemMiddleware(backend=maybe_backend)
    else:
        raise

When it happens

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

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

Related errors

• Failed to download {path}: {response.error}
• `history_path_prefix` was removed in deepagents 0.7. Configu
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32601

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/209de7bcac0b8cf6. Report an issue: GitHub.