{"record":{"id":"13199072cf9c207c","repo":"langchain-ai/deepagents","slug":"local-filesystem-backend-is-unavailable","errorCode":null,"errorMessage":"Local filesystem backend is unavailable.","messagePattern":"Local filesystem backend is unavailable\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_repository_bounds.py","lineNumber":136,"sourceCode":"\n    @staticmethod\n    def safe_pattern(pattern: str) -> bool:\n        \"\"\"Return whether a relative or absolute glob pattern cannot traverse.\"\"\"\n        path = PurePosixPath(pattern.replace(\"\\\\\", \"/\"))\n        return \"..\" not in path.parts and \"~\" not in pattern\n\n    def _resolve_filesystem_path(self, raw_path: str) -> Path:\n        \"\"\"Resolve a backend path to its canonical local filesystem target.\n\n        Returns:\n            The canonical host path used by the local filesystem backend.\n\n        Raises:\n            RuntimeError: If called for a backend without local filesystem access.\n        \"\"\"\n        if self._filesystem is None:\n            msg = \"Local filesystem backend is unavailable.\"\n            raise RuntimeError(msg)\n        if self._filesystem.virtual_mode:\n            return (self._filesystem.cwd / raw_path.lstrip(\"/\")).resolve(strict=False)\n        return Path(raw_path).resolve(strict=False)\n\n    def _filesystem_contains(self, raw_path: str) -> bool:\n        \"\"\"Return whether a local path canonically resolves below the root.\"\"\"\n        if self._filesystem is None:\n            return True\n        if self._filesystem_root is None:\n            return False\n        try:\n            resolved = self._resolve_filesystem_path(raw_path)\n        except _BACKEND_ERRORS:\n            logger.warning(\n                \"Local repository containment check failed; treating the path as \"\n                \"unavailable\",\n                exc_info=True,\n            )","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_repository_bounds.py#L118-L154","documentation":"`RepositoryBounds._resolve_filesystem_path` raises this `RuntimeError` when it is asked to map a backend path to a canonical local filesystem path but the instance was constructed with a backend that is neither a `SandboxBackendProtocol` nor a local `FilesystemBackend`. In that case `self._filesystem` is `None` (the backend has no local filesystem surface), so resolving a host path is meaningless. Direct calls raise; `__init__` and `_filesystem_contains` catch backend faults and degrade gracefully rather than crash.","triggerScenarios":"Calling `_resolve_filesystem_path` (or `_filesystem_contains` in the rare path where resolution is attempted with `_filesystem_root` unset due to earlier failure) on a `RepositoryBounds` built with an in-memory or custom backend; invoking the private helper from custom tooling against a sandbox-less composite backend.","commonSituations":"Tests or scripts wiring `RepositoryBounds` to a stub/in-memory backend and then exercising local-path containment logic; custom backend implementations that do not subclass `FilesystemBackend`; code copied from a filesystem-backed setup and reused with a remote backend.","solutions":["Construct `RepositoryBounds` with a `FilesystemBackend` (local filesystem) if you need local-path resolution.","Use a `SandboxBackendProtocol`-compliant sandbox backend so paths resolve through the sandbox instead.","Do not call `_resolve_filesystem_path`/`_filesystem_contains` for backends without local filesystem access; rely on the public `safe_path`/`safe_pattern` checks instead.","Guard with `bounds._filesystem is not None` (or catch `RuntimeError`) before attempting filesystem-specific logic."],"exampleFix":"// before\nresolved = bounds._resolve_filesystem_path(\"/src/main.py\")\n// after\nif bounds.safe_path(\"/src/main.py\"):\n    ...  # use public containment API instead of local resolution","handlingStrategy":"try-catch","validationCode":"from deepagents_code._repository_bounds import RepositoryBounds\n\ndef has_local_filesystem(bounds: RepositoryBounds) -> bool:\n    return getattr(bounds, \"_filesystem\", None) is not None","typeGuard":"from deepagents.backends import FilesystemBackend\n\ndef supports_local_resolution(backend) -> bool:\n    return isinstance(backend, FilesystemBackend)","tryCatchPattern":"try:\n    resolved = bounds._resolve_filesystem_path(path)\nexcept RuntimeError:\n    resolved = None  # backend has no local filesystem; use sandbox APIs","preventionTips":["Only exercise filesystem-path resolution when the backend is a FilesystemBackend or sandbox.","Prefer the public safe_path()/safe_pattern() API over private resolution helpers.","In tests, pick the backend fixture matching the path-assertions being made.","Remember init and _filesystem_contains already swallow backend faults; only direct calls raise."],"tags":["backend","runtime","path-validation"],"backgroundTag":"backend-capability-missing","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}