{"record":{"id":"6a7a169ceec5ca89","repo":"langchain-ai/deepagents","slug":"invalid-backend-route-prefix-prefix-r-use-lower","errorCode":null,"errorMessage":"Invalid backend route prefix {prefix!r}: use lowercase path segments and include leading and trailing slashes","messagePattern":"Invalid backend route prefix (.+?): use lowercase path segments and include leading and trailing slashes","errorType":"validation","errorClass":"ExtensionError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/extensions/api.py","lineNumber":166,"sourceCode":"        `CompositeBackend`. Shell execution remains on the default backend and\n        cannot access routed virtual content.\n\n        Args:\n            prefix: Lowercase absolute path ending in `/`, such as `/memories/`.\n            backend: Backend serving file operations under the prefix.\n\n        Raises:\n            ExtensionError: If the prefix or backend is invalid.\n        \"\"\"\n        self._ensure_active()\n        from deepagents.backends.protocol import BackendProtocol\n\n        if _ROUTE_PREFIX.fullmatch(prefix) is None:\n            msg = (\n                f\"Invalid backend route prefix {prefix!r}: use lowercase path \"\n                \"segments and include leading and trailing slashes\"\n            )\n            raise ExtensionError(msg)\n        if not isinstance(backend, BackendProtocol):\n            msg = (\n                f\"Backend route {prefix!r} got {type(backend).__name__}, \"\n                \"which is not a BackendProtocol\"\n            )\n            raise ExtensionError(msg)\n        self._registry.add_backend_route(prefix, backend, self._source)\n\n    def on_shutdown(self, hook: Callable[[], Any]) -> None:\n        \"\"\"Register a deterministic session teardown callback.\n\n        Args:\n            hook: Sync or async zero-argument callback.\n\n        Raises:\n            ExtensionError: If `hook` is not callable.\n        \"\"\"\n        self._ensure_active()","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/extensions/api.py#L148-L184","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rewrite the prefix as lowercase slash-delimited segments with both leading and trailing slashes, e.g. '/my-feature/'","Remove invalid characters (uppercase, underscores, dots, whitespace) from each segment","Check for doubled slashes or empty segments and collapse them","If the prefix is computed, validate it with the same pattern before calling the API"],"exampleFix":"// before\next.register_backend_route(\"MyRoute\", backend)\n\n// after\next.register_backend_route(\"/my-route/\", backend)","handlingStrategy":"validation","validationCode":"import re\n_ROUTE_PREFIX = re.compile(r\"^/[a-z0-9]+(?:-[a-z0-9]+)*/$\")\n\nassert _ROUTE_PREFIX.fullmatch(\"/my-route/\"), \"invalid prefix\"\next.register_backend_route(\"/my-route/\", backend)","typeGuard":"import re\n\ndef is_valid_route_prefix(prefix: str) -> bool:\n    return isinstance(prefix, str) and re.fullmatch(r\"^/[a-z0-9]+(?:-[a-z0-9]+)*/$\", prefix) is not None","tryCatchPattern":"try:\n    ext.register_backend_route(prefix, backend)\nexcept ExtensionError as exc:\n    logger.error(\"bad route prefix %r: %s\", prefix, exc)","preventionTips":["Adopt a helper that normalizes prefixes to '/lowercase-segments/' form","Never build prefixes with raw string concatenation; validate before use","Keep prefixes lowercase kebab-case with both boundary slashes"],"tags":["extensions","backend-route","validation"],"backgroundTag":"invalid-route-prefix","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}