langchain-ai/deepagents · error · ExtensionError

Extension backend route {item.name!r} from {item.source.labe

Error message

Extension backend route {item.name!r} from {item.source.label} overlaps an internal route

What it means

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.

Source

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

    Args:
        item: Backend route registration to validate.
        protected_routes: Internal route prefixes unavailable to extensions.
        sandbox_active: Whether the default execution backend is sandboxed.

    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":

View on GitHub (pinned to a1af029e6e)

Solutions

1. Change the extension's route prefix to a distinct, extension-specific namespace (e.g. '/myext/')
2. Review the protected_routes list passed to the host policy and pick a prefix outside it
3. If you maintain the host, keep extensions on a dedicated namespace and reject collisions early
4. Check for recently updated extensions that may have introduced the conflicting route

Example fix

// before
ext.register_backend_route("/files/", my_backend)

// after
ext.register_backend_route("/myext-files/", my_backend)

PROTECTED = {"/files/", "/memory/"}  # mirrors host protected_routes

assert not any(prefix.startswith(p) or p.startswith(prefix) for p in PROTECTED), \
    "route prefix overlaps protected internal route"
ext.register_backend_route(prefix, backend)

def is_unprotected(prefix: str, protected: list[str]) -> bool:
    return not any(prefix == p or prefix.startswith(p) or p.startswith(prefix) for p in protected)

try:
    ext.register_backend_route(prefix, backend)
except ExtensionError as exc:
    logger.error("route %r rejected by policy: %s", prefix, exc)

When it happens

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

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

Related errors

• Invalid backend route prefix {prefix!r}: use lowercase path
• Backend route {prefix!r} got {type(backend).__name__}, which
• Extension backend route {item.name!r} from {item.source.labe
• Workspace policy and fingerprint must be configured together
• Extension registration is closed for this session

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