langchain-ai/deepagents · error · ValueError

read_file must be included in tools; it is required by Files

Error message

read_file must be included in tools; it is required by FilesystemMiddleware

What it means

FilesystemMiddleware.__init__ requires 'read_file' in the tools list when tools is given as a list, because other filesystem features depend on read_file being available. Constructing the middleware with a tools list that omits it raises this ValueError.

Source

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

            tools: Allowlist of tool names to expose to the model.
                ``"all"` indicates all tools. If unset, defaults to `"all"`.
                Pass a list containing any of `"ls"`, `"read_file"`,
                `"write_file"`, `"edit_file"`, `"delete"`, `"glob"`,
                `"grep"`, `"execute"` to restrict the model to only those
                tools; all others are hidden. `read_file` must be included
                in any list. Backend capability checks for `execute` and
                `delete` still apply; listing them when the backend does not
                support them is a no-op.
            _permissions: Optional filesystem permission rules enforced directly
                by this middleware's tool implementations.

                Marked private for now because this is an internal
                implementation detail and may move to the backend layer in a
                future change.
        """
        if isinstance(tools, list) and "read_file" not in tools:
            msg = "read_file must be included in tools; it is required by FilesystemMiddleware"
            raise ValueError(msg)
        if max_execute_timeout <= 0:
            msg = f"max_execute_timeout must be positive, got {max_execute_timeout}"
            raise ValueError(msg)
        if grep_max_count is not None and grep_max_count <= 0:
            msg = f"grep_max_count must be positive or None, got {grep_max_count}"
            raise ValueError(msg)
        # Use provided backend or default to StateBackend instance
        self.backend = backend if backend is not None else StateBackend()
        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,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add "read_file" to the tools list
2. Pass tools=None (or the default set) to get the standard toolset
3. Rework your tool-filtering logic to treat read_file as mandatory

Example fix

// before
FilesystemMiddleware(tools=["write_file", "edit_file"])
// after
FilesystemMiddleware(tools=["read_file", "write_file", "edit_file"])

REQUIRED_TOOLS = {"read_file"}
def validate_tools(tools: list[str] | None) -> list[str] | None:
    if tools is not None and not REQUIRED_TOOLS.issubset(tools):
        raise ValueError(f"tools must include {REQUIRED_TOOLS}")
    return tools

When it happens

Trigger: FilesystemMiddleware(tools=["write_file", "ls", ...]) with "read_file" missing; programmatically filtering tools and dropping read_file.

Common situations: Slimming the toolset for cost/safety and unknowingly removing the required baseline tool; passing tools as a list (not None/ full set) after customization.

Related errors

• Permission path must start with '/': {path!r}
• max_execute_timeout must be positive, got {max_execute_timeo
• allow_list must not be empty; disable shell access instead
• interpreter_ptc='all' exposes every host tool to PTC calls t
• Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al

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