langchain-ai/deepagents · error · NotImplementedError

FilesystemMiddleware does not yet support permissions with b

Error message

FilesystemMiddleware does not yet support permissions with backends that provide command execution (SandboxBackendProtocol). Tool-level permissions for the execute tool are not implemented. Either remove permissions or use a backend without execution support.

What it means

FilesystemMiddleware raises NotImplementedError when both custom permissions and an execution-capable backend (SandboxBackendProtocol) are used together. Tool-level permissions for the execute tool are not yet implemented, so the combination is unsupported rather than silently unenforced.

Source

Thrown at libs/deepagents/deepagents/middleware/filesystem.py:1724

        if callable(self.backend) and not isinstance(self.backend, BackendProtocol):
            msg = (
                "backend must be an initialized backend instance. Backend factories "
                "were removed in deepagents 0.7; pass StateBackend(), "
                "CompositeBackend(...), or another BackendProtocol instance instead."
            )
            raise TypeError(msg)
        self.state_schema = cast(
            "type[FilesystemState]",
            FilesystemState if _uses_state_backend(self.backend) else AgentState,
        )
        if _permissions and supports_execution(self.backend) and not _all_paths_scoped_to_routes(_permissions, self.backend):
            msg = (
                "FilesystemMiddleware does not yet support permissions with backends that "
                "provide command execution (SandboxBackendProtocol). Tool-level permissions "
                "for the execute tool are not implemented. Either remove permissions or use "
                "a backend without execution support."
            )
            raise NotImplementedError(msg)

        artifacts_root = self.backend.artifacts_root if isinstance(self.backend, CompositeBackend) else "/"
        _root = artifacts_root.rstrip("/")
        self._large_tool_results_prefix = f"{_root}/large_tool_results"
        self._conversation_history_prefix = f"{_root}/conversation_history"

        # Store configuration (private - internal implementation details)
        self._custom_system_prompt = system_prompt
        self._custom_tool_descriptions = custom_tool_descriptions or {}
        self._tool_token_limit_before_evict = tool_token_limit_before_evict
        self._human_message_token_limit_before_evict = human_message_token_limit_before_evict
        self._max_execute_timeout = max_execute_timeout
        self._grep_max_count = grep_max_count
        if isinstance(tools, list):
            self._enabled_tools: frozenset[str] | None = frozenset(tools)
        elif tools == "all":
            self._enabled_tools = frozenset(_ALL_FS_TOOL_NAMES)
        else:  # None -- user did not specify, defaults to all tools opted-in

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Remove the permissions argument when using an execution-capable backend
  2. Use a backend without execution support (e.g. StateBackend) if permissions are required
  3. Scope all permission paths to routes if that satisfies the _all_paths_scoped_to_routes check
  4. Wait for/track upstream support for execute-tool permissions

Example fix

// before
mw = FilesystemMiddleware(permissions=my_permissions, backend=SandboxBackend())
// after
mw = FilesystemMiddleware(backend=SandboxBackend())  # permissions dropped, or use StateBackend with permissions
Defensive patterns

Strategy: validation

Validate before calling

from deepagents.backends import supports_execution

def check_permissions_backend_combo(permissions, backend):
    if permissions and supports_execution(backend):
        raise NotImplementedError("Permissions are unsupported with execution-capable backends")

Type guard

def combo_supported(permissions, backend) -> bool:
    return not (permissions and supports_execution(backend))

Try / catch

try:
    mw = FilesystemMiddleware(permissions=perms, backend=backend)
except NotImplementedError:
    logger.warning("Permissions unsupported with execution backend; dropping permissions")
    mw = FilesystemMiddleware(backend=backend)

Prevention

When it happens

Trigger: Calling FilesystemMiddleware(permissions=..., backend=SandboxBackend(...)) (or any backend satisfying SandboxBackendProtocol) where the permissions are not all scoped to routes.

Common situations: Developers wanting to sandbox command execution while restricting file access via permissions; the sandbox backend provides execute, which permissions cannot yet gate.

Related errors

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