{"record":{"id":"0adda46491318b28","repo":"langchain-ai/deepagents","slug":"extension-backend-route-item-name-r-from-item-s-0adda4","errorCode":null,"errorMessage":"Extension backend route {item.name!r} from {item.source.label} cannot mount {type(item.unit).__name__} in sandbox mode","messagePattern":"Extension backend route (.+?) from (.+?) cannot mount (.+?) in sandbox mode","errorType":"exception","errorClass":"ExtensionError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/extensions/hosting.py","lineNumber":149,"sourceCode":"    Raises:\n        ExtensionError: If the route overlaps internal storage or directly\n            exposes a host filesystem backend to a sandboxed agent.\n    \"\"\"\n    if any(\n        item.name.startswith(prefix) or prefix.startswith(item.name)\n        for prefix in protected_routes\n    ):\n        msg = (\n            f\"Extension backend route {item.name!r} from {item.source.label} \"\n            \"overlaps an internal route\"\n        )\n        raise ExtensionError(msg)\n    if sandbox_active and isinstance(item.unit, FilesystemBackend):\n        msg = (\n            f\"Extension backend route {item.name!r} from {item.source.label} \"\n            f\"cannot mount {type(item.unit).__name__} in sandbox mode\"\n        )\n        raise ExtensionError(msg)\n\n\ndef bind_runtime_host_policy(\n    registry: ExtensionRegistry,\n    protected_routes: Collection[str],\n    *,\n    sandbox_active: bool = False,\n) -> None:\n    \"\"\"Validate late routes and flag graph-bound registrations for restart.\"\"\"\n\n    def apply(kind: str, item: RegisteredUnit[Any]) -> None:\n        if kind == \"middleware\":\n            registry.require_restart()\n            return\n        if kind == \"backend_route\":\n            validate_backend_route(\n                item, protected_routes, sandbox_active=sandbox_active\n            )","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/extensions/hosting.py#L131-L167","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Disable sandbox mode if the extension's filesystem route is intentionally required","Use an extension whose backend is not a FilesystemBackend (e.g. a virtual/in-memory backend)","Update or replace the extension with a sandbox-compatible version","Contact the extension author to expose a non-filesystem backend option"],"exampleFix":"// before\next.register_backend_route(\"/data/\", FilesystemBackend(root=\"/data\"))\n\n// after\next.register_backend_route(\"/data/\", InMemoryBackend(data))  # sandbox-safe","handlingStrategy":"validation","validationCode":"from deepagents_code.extensions.hosting import validate_backend_route  # policy lives here\n\ndef is_sandbox_safe(unit) -> bool:\n    from langchain.backends import FilesystemBackend  # illustrative import\n    return not (sandbox_active and isinstance(unit, FilesystemBackend))","typeGuard":"def is_sandbox_compatible(backend) -> bool:\n    return not isinstance(backend, FilesystemBackend)","tryCatchPattern":"try:\n    ext.register_backend_route(prefix, backend)\nexcept ExtensionError as exc:\n    logger.error(\"sandbox rejected backend %s: %s\", type(backend).__name__, exc)","preventionTips":["Use virtual/in-memory backends in extensions intended for sandboxed runs","Document sandbox requirements on your extension","Test extensions with sandbox mode enabled before distribution"],"tags":["extensions","backend-route","sandbox","security-policy"],"backgroundTag":"sandbox-policy-violation","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}