langchain-ai/deepagents · error · NotImplementedError

Default backend doesn't support command execution (SandboxBa

Error message

Default backend doesn't support command execution (SandboxBackendProtocol). To enable execution, provide a default backend that implements SandboxBackendProtocol.

What it means

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.

Source

Thrown at libs/deepagents/deepagents/backends/composite.py:850

            `ExecuteResponse` with output, exit code, and truncation flag.

        Raises:
            NotImplementedError: If the default backend is not a
                [`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol]
                (i.e., it doesn't support execution).
        """
        if isinstance(self.default, SandboxBackendProtocol):
            if timeout is not None and execute_accepts_timeout(type(self.default)):
                return self.default.execute(command, timeout=timeout)
            return self.default.execute(command)

        # This shouldn't be reached if the runtime check in the execute tool works correctly,
        # but we include it as a safety fallback.
        msg = (
            "Default backend doesn't support command execution (SandboxBackendProtocol). "
            "To enable execution, provide a default backend that implements SandboxBackendProtocol."
        )
        raise NotImplementedError(msg)

    async def aexecute(
        self,
        command: str,
        *,
        # ASYNC109 - timeout is a semantic parameter forwarded to the underlying
        # backend's implementation, not an asyncio.timeout() contract.
        timeout: int | None = None,  # noqa: ASYNC109
    ) -> ExecuteResponse:
        """Async version of execute.

        See `execute()` for detailed documentation on parameters and behavior.
        """
        if isinstance(self.default, SandboxBackendProtocol):
            if timeout is not None and execute_accepts_timeout(type(self.default)):
                return await self.default.aexecute(command, timeout=timeout)
            return await self.default.aexecute(command)

View on GitHub (pinned to a1af029e6e)

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.

Example fix

// before
backend = CompositeBackend(default=FilesystemBackend(root="./ws"))
backend.execute("ls")
// after
backend = CompositeBackend(default=SandboxedShellBackend(root="./ws"))
backend.execute("ls")

Defensive patterns

Strategy: type-guard

Validate before calling

from deepagents.backends.protocols import SandboxBackendProtocol
if not isinstance(backend.default, SandboxBackendProtocol):
    raise RuntimeError("configure an execution-capable default backend before enabling execute")

Type guard

def supports_execution(backend: object) -> TypeGuard[SandboxBackendProtocol]:
    return isinstance(backend, SandboxBackendProtocol)

Try / catch

try:
    result = backend.execute(cmd)
except NotImplementedError:
    result = reject_execution(cmd)  # inform the model execution is unavailable

Prevention

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.

When it happens

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

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

Related errors

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