langchain-ai/deepagents · error · RuntimeError

Local filesystem backend is unavailable.

Error message

Local filesystem backend is unavailable.

What it means

`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.

Source

Thrown at libs/code/deepagents_code/_repository_bounds.py:136

    @staticmethod
    def safe_pattern(pattern: str) -> bool:
        """Return whether a relative or absolute glob pattern cannot traverse."""
        path = PurePosixPath(pattern.replace("\\", "/"))
        return ".." not in path.parts and "~" not in pattern

    def _resolve_filesystem_path(self, raw_path: str) -> Path:
        """Resolve a backend path to its canonical local filesystem target.

        Returns:
            The canonical host path used by the local filesystem backend.

        Raises:
            RuntimeError: If called for a backend without local filesystem access.
        """
        if self._filesystem is None:
            msg = "Local filesystem backend is unavailable."
            raise RuntimeError(msg)
        if self._filesystem.virtual_mode:
            return (self._filesystem.cwd / raw_path.lstrip("/")).resolve(strict=False)
        return Path(raw_path).resolve(strict=False)

    def _filesystem_contains(self, raw_path: str) -> bool:
        """Return whether a local path canonically resolves below the root."""
        if self._filesystem is None:
            return True
        if self._filesystem_root is None:
            return False
        try:
            resolved = self._resolve_filesystem_path(raw_path)
        except _BACKEND_ERRORS:
            logger.warning(
                "Local repository containment check failed; treating the path as "
                "unavailable",
                exc_info=True,
            )

View on GitHub (pinned to a1af029e6e)

Solutions

1. Construct `RepositoryBounds` with a `FilesystemBackend` (local filesystem) if you need local-path resolution.
2. Use a `SandboxBackendProtocol`-compliant sandbox backend so paths resolve through the sandbox instead.
3. Do not call `_resolve_filesystem_path`/`_filesystem_contains` for backends without local filesystem access; rely on the public `safe_path`/`safe_pattern` checks instead.
4. Guard with `bounds._filesystem is not None` (or catch `RuntimeError`) before attempting filesystem-specific logic.

Example fix

// before
resolved = bounds._resolve_filesystem_path("/src/main.py")
// after
if bounds.safe_path("/src/main.py"):
    ...  # use public containment API instead of local resolution

from deepagents_code._repository_bounds import RepositoryBounds

def has_local_filesystem(bounds: RepositoryBounds) -> bool:
    return getattr(bounds, "_filesystem", None) is not None

from deepagents.backends import FilesystemBackend

def supports_local_resolution(backend) -> bool:
    return isinstance(backend, FilesystemBackend)

try:
    resolved = bounds._resolve_filesystem_path(path)
except RuntimeError:
    resolved = None  # backend has no local filesystem; use sandbox APIs

When it happens

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

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

Related errors

• Agent backend did not publish its offload operation; /offloa
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path
• Repository root must be an absolute contained path: {root!r}
• SDK {name} tool is unavailable.
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path

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