agentscope-ai/agentscope · warning · RipgrepTimeoutError

Ripgrep search timed out after {timeout} seconds. Try search

Error message

Ripgrep search timed out after {timeout} seconds. Try searching a more specific path or pattern.

What it means

RipgrepTimeoutError raised when the grep tool's shell execution of rg exceeds the requested timeout (exit_code -1, stderr 'timed out'). It carries an empty result list.

Source

Thrown at src/agentscope/tool/_builtin/_grep.py:297

        search_path: str,
        timeout: int = 30,
    ) -> list[str]:
        """Run ripgrep and return output lines.

        Builds an argument vector and dispatches it through
        ``backend.exec_shell`` (which runs the program directly, without
        a shell), so the same code path works for local, Docker, and E2B
        backends and needs no platform-specific argument quoting.
        """
        command = ["rg", *args, search_path]

        result = await self._backend.exec_shell(
            command,
            timeout=float(timeout),
        )

        if result.exit_code == -1 and result.stderr == b"timed out":
            raise RipgrepTimeoutError(
                f"Ripgrep search timed out after {timeout} seconds. "
                "Try searching a more specific path or pattern.",
                [],
            )

        # returncode 0 = matches found, 1 = no matches
        if result.exit_code not in (0, 1):
            error_msg = result.stderr.decode(
                "utf-8",
                errors="ignore",
            ).strip()
            raise RuntimeError(
                f"ripgrep error (code {result.exit_code}): {error_msg}",
            )

        raw = result.stdout.decode("utf-8", errors="ignore")

        lines = [

View on GitHub (pinned to e90f1c7592)

Solutions

1. Narrow the search path and/or pattern
2. Increase the timeout argument
3. Exclude heavy dirs (node_modules, .git, venv) via ripgrep glob excludes
4. Catch RipgrepTimeoutError and retry with narrower scope

Example fix

# before
results = await grep(pattern='foo', path='/', timeout=10)
# after
results = await grep(pattern='foo', path='src', timeout=60)

import os
scope_ok = os.path.isdir(path) and path not in ('/', os.path.expanduser('~'))

try:
    res = await grep(pattern=pat, path=path, timeout=30)
except RipgrepTimeoutError:
    res = await grep(pattern=pat, path=shorter_subdir, timeout=120)

When it happens

Trigger: GrepTool call over a huge directory tree, broad pattern, or slow filesystem (NFS, node_modules, home dir) with a small timeout value.

Common situations: Agents searching '/' or large monorepos; low timeout defaults combined with cold caches or network mounts.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• ripgrep error (code {result.exit_code}): {error_msg}
• Vector search index {self._index_name!r} on collection {coll
• {self.__class__.__name__} does not implement call
• {type(self).__name__} must be called with keyword arguments
• Invalid input_schema: {self.tool.input_schema}.

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/570c97b920053b47. Report an issue: GitHub.