{"record":{"id":"177f24546537480e","repo":"langchain-ai/deepagents","slug":"default-backend-doesn-t-support-command-execution","errorCode":null,"errorMessage":"Default backend doesn't support command execution (SandboxBackendProtocol). To enable execution, provide a default backend that implements SandboxBackendProtocol.","messagePattern":"Default backend doesn't support command execution \\(SandboxBackendProtocol\\)\\. To enable execution, provide a default backend that implements SandboxBackendProtocol\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/backends/composite.py","lineNumber":850,"sourceCode":"            `ExecuteResponse` with output, exit code, and truncation flag.\n\n        Raises:\n            NotImplementedError: If the default backend is not a\n                [`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol]\n                (i.e., it doesn't support execution).\n        \"\"\"\n        if isinstance(self.default, SandboxBackendProtocol):\n            if timeout is not None and execute_accepts_timeout(type(self.default)):\n                return self.default.execute(command, timeout=timeout)\n            return self.default.execute(command)\n\n        # This shouldn't be reached if the runtime check in the execute tool works correctly,\n        # but we include it as a safety fallback.\n        msg = (\n            \"Default backend doesn't support command execution (SandboxBackendProtocol). \"\n            \"To enable execution, provide a default backend that implements SandboxBackendProtocol.\"\n        )\n        raise NotImplementedError(msg)\n\n    async def aexecute(\n        self,\n        command: str,\n        *,\n        # ASYNC109 - timeout is a semantic parameter forwarded to the underlying\n        # backend's implementation, not an asyncio.timeout() contract.\n        timeout: int | None = None,  # noqa: ASYNC109\n    ) -> ExecuteResponse:\n        \"\"\"Async version of execute.\n\n        See `execute()` for detailed documentation on parameters and behavior.\n        \"\"\"\n        if isinstance(self.default, SandboxBackendProtocol):\n            if timeout is not None and execute_accepts_timeout(type(self.default)):\n                return await self.default.aexecute(command, timeout=timeout)\n            return await self.default.aexecute(command)\n","sourceCodeStart":832,"sourceCodeEnd":868,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/backends/composite.py#L832-L868","documentation":"The composite backend's synchronous `execute` fell through to its default backend, which does not implement `SandboxBackendProtocol`, so command execution is impossible. The method raises `NotImplementedError` as a safety fallback — normally the execute tool's runtime check catches this earlier and never calls into the backend.","triggerScenarios":"Calling `execute` (or the execute tool path) on a `CompositeBackend` whose routed/default backend is a plain file backend that lacks `SandboxBackendProtocol`'s execution support.","commonSituations":"Constructing a `CompositeBackend` with only file-oriented backends and then asking the agent to run shell commands; forgetting to supply an execution-capable default backend; sandbox not configured in the environment.","solutions":["Provide a default backend implementing `SandboxBackendProtocol` (e.g. a sandboxed/local execution backend) when building the `CompositeBackend`.","Route execution-capable backends for the paths being executed against so the default is never hit.","Disable/guard command-execution tool usage in the agent if execution is intentionally unsupported."],"exampleFix":"// before\nbackend = CompositeBackend(default=FilesystemBackend(root=\"./ws\"))\nbackend.execute(\"ls\")\n// after\nbackend = CompositeBackend(default=SandboxedShellBackend(root=\"./ws\"))\nbackend.execute(\"ls\")","handlingStrategy":"type-guard","validationCode":"from deepagents.backends.protocols import SandboxBackendProtocol\nif not isinstance(backend.default, SandboxBackendProtocol):\n    raise RuntimeError(\"configure an execution-capable default backend before enabling execute\")","typeGuard":"def supports_execution(backend: object) -> TypeGuard[SandboxBackendProtocol]:\n    return isinstance(backend, SandboxBackendProtocol)","tryCatchPattern":"try:\n    result = backend.execute(cmd)\nexcept NotImplementedError:\n    result = reject_execution(cmd)  # inform the model execution is unavailable","preventionTips":["Always wire a `SandboxBackendProtocol`-implementing default backend when execution is expected.","Test `backend.execute(\"echo ok\")` in CI for every backend configuration.","Disable the execute tool in agents deployed without a sandbox backend."],"tags":["backend","execution","sandbox","not-implemented"],"backgroundTag":"backend-does-not-support-execution","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}