langchain-ai/deepagents · error · ExtensionError

Invalid backend route prefix {prefix!r}: use lowercase path

Error message

Invalid backend route prefix {prefix!r}: use lowercase path segments and include leading and trailing slashes

What it means

Raised by ExtensionApi.register_backend_route when the given prefix does not match the _ROUTE_PREFIX pattern. Valid prefixes are lowercase path segments with a leading and trailing slash (e.g. "/my-ext/"). The route is rejected before any mounting happens.

Source

Thrown at libs/code/deepagents_code/extensions/api.py:166

        `CompositeBackend`. Shell execution remains on the default backend and
        cannot access routed virtual content.

        Args:
            prefix: Lowercase absolute path ending in `/`, such as `/memories/`.
            backend: Backend serving file operations under the prefix.

        Raises:
            ExtensionError: If the prefix or backend is invalid.
        """
        self._ensure_active()
        from deepagents.backends.protocol import BackendProtocol

        if _ROUTE_PREFIX.fullmatch(prefix) is None:
            msg = (
                f"Invalid backend route prefix {prefix!r}: use lowercase path "
                "segments and include leading and trailing slashes"
            )
            raise ExtensionError(msg)
        if not isinstance(backend, BackendProtocol):
            msg = (
                f"Backend route {prefix!r} got {type(backend).__name__}, "
                "which is not a BackendProtocol"
            )
            raise ExtensionError(msg)
        self._registry.add_backend_route(prefix, backend, self._source)

    def on_shutdown(self, hook: Callable[[], Any]) -> None:
        """Register a deterministic session teardown callback.

        Args:
            hook: Sync or async zero-argument callback.

        Raises:
            ExtensionError: If `hook` is not callable.
        """
        self._ensure_active()

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rewrite the prefix as lowercase slash-delimited segments with both leading and trailing slashes, e.g. '/my-feature/'
2. Remove invalid characters (uppercase, underscores, dots, whitespace) from each segment
3. Check for doubled slashes or empty segments and collapse them
4. If the prefix is computed, validate it with the same pattern before calling the API

Example fix

// before
ext.register_backend_route("MyRoute", backend)

// after
ext.register_backend_route("/my-route/", backend)

import re
_ROUTE_PREFIX = re.compile(r"^/[a-z0-9]+(?:-[a-z0-9]+)*/$")

assert _ROUTE_PREFIX.fullmatch("/my-route/"), "invalid prefix"
ext.register_backend_route("/my-route/", backend)

import re

def is_valid_route_prefix(prefix: str) -> bool:
    return isinstance(prefix, str) and re.fullmatch(r"^/[a-z0-9]+(?:-[a-z0-9]+)*/$", prefix) is not None

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

When it happens

Trigger: Calling `ext.register_backend_route(prefix, backend)` with a prefix missing the leading or trailing slash, containing uppercase characters, underscores, spaces, empty segments ('//'), or otherwise failing the regex fullmatch.

Common situations: Typing '/MyRoute' or 'myroute' instead of '/myroute/'; forgetting the trailing slash; building prefixes with string concatenation that leaves '//'; using characters like '_' or '.' in segment names.

Related errors

• Backend route {prefix!r} got {type(backend).__name__}, which
• Extension backend route {item.name!r} from {item.source.labe
• Extension backend route {item.name!r} from {item.source.labe
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory

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