langchain-ai/deepagents · error · ValueError

grep_max_count must be positive or None, got {grep_max_count

Error message

grep_max_count must be positive or None, got {grep_max_count}

What it means

FilesystemMiddleware validates `grep_max_count` in `__init__` and raises ValueError if it is not None and not a positive integer. This cap limits how many grep results can be returned; a non-positive value would make the grep tool useless or produce confusing behavior, so it is rejected eagerly at construction time.

Source

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

                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,
        )
        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 "

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Pass a positive integer, e.g. FilesystemMiddleware(grep_max_count=50)
  2. Pass None if you want unlimited grep results
  3. Fix the config/env source so the default is a positive value instead of 0

Example fix

// before
mw = FilesystemMiddleware(grep_max_count=0)
// after
mw = FilesystemMiddleware(grep_max_count=50)  # or None for unlimited
Defensive patterns

Strategy: validation

Validate before calling

def check_grep_max_count(v):
    if v is not None and (not isinstance(v, int) or isinstance(v, bool) or v <= 0):
        raise ValueError(f"grep_max_count must be positive or None, got {v}")
    return v
# call before constructing FilesystemMiddleware

Type guard

def is_positive_int_or_none(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)

Try / catch

try:
    mw = FilesystemMiddleware(grep_max_count=cfg.grep_max_count)
except ValueError as e:
    logger.error("Invalid middleware config: %s", e)
    raise

Prevention

When it happens

Trigger: Constructing FilesystemMiddleware(grep_max_count=0) or grep_max_count=-1 (or any value <= 0). Only None (unlimited) or a positive integer is accepted.

Common situations: Config-driven setups where the grep cap is read from a settings file or env var defaulting to 0, or code that computes the cap dynamically (e.g. len(results) of an empty list) before passing it in.

Related errors

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