{"record":{"id":"0f17318e98a2aab6","repo":"langchain-ai/deepagents","slug":"extension-backend-route-item-name-r-from-item-s","errorCode":null,"errorMessage":"Extension backend route {item.name!r} from {item.source.label} overlaps an internal route","messagePattern":"Extension backend route (.+?) from (.+?) overlaps an internal route","errorType":"exception","errorClass":"ExtensionError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/extensions/hosting.py","lineNumber":143,"sourceCode":"\n    Args:\n        item: Backend route registration to validate.\n        protected_routes: Internal route prefixes unavailable to extensions.\n        sandbox_active: Whether the default execution backend is sandboxed.\n\n    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\":","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/extensions/hosting.py#L125-L161","documentation":"Raised by validate_backend_route when an extension-provided backend route prefix overlaps a route reserved for internal use (protected_routes). Extensions may not shadow the agent's built-in virtual filesystem paths.","triggerScenarios":"An extension calls register_backend_route with a prefix equal to, or nested under, one of the protected internal routes (e.g. '/files/', '/memory/'), and the route policy is then validated during agent creation (create_cli_agent) or apply.","commonSituations":"Choosing a generic prefix like '/tmp/' or '/fs/' that collides with reserved namespaces; an extension upgrade that added a new default route conflicting with internals; multiple extensions agreeing on a prefix that happens to be protected.","solutions":["Change the extension's route prefix to a distinct, extension-specific namespace (e.g. '/myext/')","Review the protected_routes list passed to the host policy and pick a prefix outside it","If you maintain the host, keep extensions on a dedicated namespace and reject collisions early","Check for recently updated extensions that may have introduced the conflicting route"],"exampleFix":"// before\next.register_backend_route(\"/files/\", my_backend)\n\n// after\next.register_backend_route(\"/myext-files/\", my_backend)","handlingStrategy":"validation","validationCode":"PROTECTED = {\"/files/\", \"/memory/\"}  # mirrors host protected_routes\n\nassert not any(prefix.startswith(p) or p.startswith(prefix) for p in PROTECTED), \\\n    \"route prefix overlaps protected internal route\"\next.register_backend_route(prefix, backend)","typeGuard":"def is_unprotected(prefix: str, protected: list[str]) -> bool:\n    return not any(prefix == p or prefix.startswith(p) or p.startswith(prefix) for p in protected)","tryCatchPattern":"try:\n    ext.register_backend_route(prefix, backend)\nexcept ExtensionError as exc:\n    logger.error(\"route %r rejected by policy: %s\", prefix, exc)","preventionTips":["Namespace extension routes under a unique '/<extname>/' prefix","Check the host's protected_routes list before choosing prefixes","Test route policy validation in CI for every extension route"],"tags":["extensions","backend-route","policy","namespace-collision"],"backgroundTag":"reserved-route-collision","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}