langchain-ai/deepagents · error · ExtensionError

Extension backend route

Error message

Extension backend route {item.name!r} from {item.source.label} cannot mount {type(item.unit).__name__} in sandbox mode

What it means

Raised by validate_backend_route when sandbox mode is active and an extension attempts to mount a FilesystemBackend on a backend route. In sandbox mode extensions are forbidden from mounting real filesystem backends, which could bypass sandboxing.

Solutions

1. Disable sandbox mode if the extension's filesystem route is intentionally required
2. Use an extension whose backend is not a FilesystemBackend (e.g. a virtual/in-memory backend)
3. Update or replace the extension with a sandbox-compatible version
4. Contact the extension author to expose a non-filesystem backend option

Example fix

// before
ext.register_backend_route("/data/", FilesystemBackend(root="/data"))

// after
ext.register_backend_route("/data/", InMemoryBackend(data))  # sandbox-safe

from deepagents_code.extensions.hosting import validate_backend_route  # policy lives here

def is_sandbox_safe(unit) -> bool:
    from langchain.backends import FilesystemBackend  # illustrative import
    return not (sandbox_active and isinstance(unit, FilesystemBackend))

def is_sandbox_compatible(backend) -> bool:
    return not isinstance(backend, FilesystemBackend)

try:
    ext.register_backend_route(prefix, backend)
except ExtensionError as exc:
    logger.error("sandbox rejected backend %s: %s", type(backend).__name__, exc)

When it happens

Trigger: Registering a FilesystemBackend (or subclass) route from an extension while the agent runs with sandbox enabled, then creating the agent (create_cli_agent) or applying the registry.

Common situations: An extension designed for non-sandboxed use installed into a sandboxed CLI agent; an extension upgrade that switched to a filesystem-backed route; users enabling sandbox mode after installing such an extension.

Related errors

• Backend route got , which is not a BackendProtocol
• Extension backend route
• Invalid backend route prefix
• Could not construct middleware
• Could not convert into a tool

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

Appendix: source

Thrown at libs/code/deepagents_code/extensions/hosting.py:149

    Raises:
        ExtensionError: If the route overlaps internal storage or directly
            exposes a host filesystem backend to a sandboxed agent.
    """
    if any(
        item.name.startswith(prefix) or prefix.startswith(item.name)
        for prefix in protected_routes
    ):
        msg = (
            f"Extension backend route {item.name!r} from {item.source.label} "
            "overlaps an internal route"
        )
        raise ExtensionError(msg)
    if sandbox_active and isinstance(item.unit, FilesystemBackend):
        msg = (
            f"Extension backend route {item.name!r} from {item.source.label} "
            f"cannot mount {type(item.unit).__name__} in sandbox mode"
        )
        raise ExtensionError(msg)


def bind_runtime_host_policy(
    registry: ExtensionRegistry,
    protected_routes: Collection[str],
    *,
    sandbox_active: bool = False,
) -> None:
    """Validate late routes and flag graph-bound registrations for restart."""

    def apply(kind: str, item: RegisteredUnit[Any]) -> None:
        if kind == "middleware":
            registry.require_restart()
            return
        if kind == "backend_route":
            validate_backend_route(
                item, protected_routes, sandbox_active=sandbox_active
            )

View on GitHub (pinned to a1af029e6e)