langchain-ai/deepagents · error · ValueError

context_lines must be non-negative

Error message

context_lines must be non-negative

What it means

grep validates its context_lines argument eagerly and rejects negative values with ValueError. Negative context is meaningless (it controls how many surrounding lines accompany each match), so the backend fails fast instead of producing slice-index bugs downstream.

Source

Thrown at libs/deepagents/deepagents/backends/filesystem.py:653

                `None` returns every match; an int stops the search once the cap
                is reached and flags the result with `truncated=True`.
            context_lines: Number of lines to include before and after each match.

                This is a backend-level API. It is deliberately not exposed
                through the agent-facing `grep` tool (`GrepSchema`), so matches
                returned via that tool never carry context.

        Returns:
            `GrepResult` with matches or error. When `context_lines > 0` and some
            matched files cannot be re-read for context, the matches are still
            returned and the failure is reported in `GrepResult.error`.

        Raises:
            ValueError: If `context_lines` is negative.
        """
        if context_lines < 0:
            msg = "context_lines must be non-negative"
            raise ValueError(msg)

        # Validate the include glob before choosing a search path: the shared
        # matcher refuses some patterns (e.g. any `..` segment) by raising, and
        # the Python fallback compiles it outside any error handling. Reporting
        # a refusal here keeps `grep` non-throwing on both paths -- and
        # consistent, since ripgrep would otherwise treat it as a silent
        # no-match.
        glob_refusal = self._refused_grep_glob_error(glob)
        if glob_refusal is not None:
            return GrepResult(error=glob_refusal, matches=[])

        # Resolve base path
        try:
            base_full = self._resolve_path(path or ".")
        except ValueError:
            return GrepResult(matches=[])
        except (OSError, RuntimeError) as e:
            search_path = path or "."

View on GitHub (pinned to a1af029e6e)

Solutions

1. Clamp context_lines with max(0, context_lines) before calling grep
2. Fix the arithmetic that produced the negative window size
3. Use 0 explicitly when no surrounding context is wanted

Example fix

// before
result = backend.grep(pattern, context_lines=before - after)
// after
result = backend.grep(pattern, context_lines=max(0, before - after))

context_lines = max(0, context_lines)
result = backend.grep(pattern, context_lines=context_lines)

try:
    hits = backend.grep(pattern, context_lines=ctx)
except ValueError as exc:
    if "context_lines must be non-negative" in str(exc):
        hits = backend.grep(pattern, context_lines=0)
    else:
        raise

When it happens

Trigger: Calling grep(pattern, path, glob, context_lines=-1) or passing a negative value computed from subtraction (e.g. line_num - margin where margin > line_num).

Common situations: Computing context windows dynamically where an offset can go below zero, or off-by-one in tool wrappers around grep.

Related errors

• timeout must be positive, got {timeout}
• timeout must be positive, got {effective_timeout}
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32601

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