KBCodeKB
Claude CodeUnverified

Fix Claude Code 'No Assistant Message Found' Error When Using @ Directory References on macOS, Windows, and Linux

Claude Code v2.0.22 through v2.0.26 crashes with 'Error: No assistant message found' when @-referencing directories in prompts. The error is caused by built-in ripgrep failing silently on directory scans, leaving the message pipeline with a missing assistant response. This affects all platforms (macOS, Windows, Linux) and all account types. Anthropic staff (wolffiex) confirmed the fix and shipped it in v2.0.27 (October 24, 2025). Workarounds include using relative paths instead of @ references, disabling built-in ripgrep, or downgrading to v2.0.21.

Symptoms

  • Claude Code crashes with 'Error: No assistant message found' when prompts include @directory references (e.g., '@docs/reference/')
  • Error persists across sessions and is reproducible on demand when @-referencing directories
  • Stack trace shows 'Nm (file:///...cli.js:3310:12886)' — an assertion failure in the message handling pipeline
  • Also triggered by .terraform files and certain file patterns that cause ripgrep to fail silently
  • Issue introduced in v2.0.22; v2.0.21 and earlier are unaffected

Error signatures

Error: No assistant message found
at Nm (file:///...cli.js:3310:12886)
Error: Request was aborted

Possible causes

  • Built-in ripgrep (introduced in v1.0.84) fails silently when scanning @-referenced directories, producing an empty or malformed result that the message pipeline cannot handle — the assertion 'No assistant message found' fires because the pipeline expects a valid assistant message after tool results but receives none. The regression was introduced in v2.0.22 when the @-reference handler was refactored to use ripgrep for directory indexing instead of the previous glob-based approach. This refactoring did not include error handling for ripgrep failures on binary files, special files (e.g., .terraform), or empty scan results.
  • The @ reference handler does not gracefully handle ripgrep errors on binary or special files (e.g., .terraform files), causing the indexing step to abort without propagating a proper error to the message pipeline. When ripgrep encounters a file it cannot process, it may return an empty result set, which the pipeline interprets as 'no assistant message' rather than 'indexing failed'.
  • Race condition between ripgrep's async directory scan and the message pipeline: ripgrep may return partial results or abort mid-scan on large directories with many files, leaving the pipeline in an inconsistent state where tool results exist but no corresponding assistant message was recorded. This explains why the error is intermittent for some users and reproducible on demand for others — directory size and file composition determine whether ripgrep completes before the pipeline times out.

Solutions

Disable Built-in Ripgrep (Environment Variable Workaround)

risk: lowgithubpublished

Setting USE_BUILTIN_RIPGREP=0 disables the built-in ripgrep that causes the crash. Community member davidrudduck discovered this workaround and confirmed it resolves the issue without downgrading. Use this when npm upgrade is blocked or you need an immediate fix.

  1. Set the environment variable: export USE_BUILTIN_RIPGREP=0
  2. Restart your Claude Code session (exit and re-run claude)
  3. Test with an @ directory reference to confirm the error no longer occurs
  4. To make permanent, add 'export USE_BUILTIN_RIPGREP=0' to your shell profile (~/.bashrc, ~/.zshrc, etc.)

Commands

export USE_BUILTIN_RIPGREP=0
claude
echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.bashrc

Config examples

# Add to ~/.bashrc or ~/.zshrc for persistence:
export USE_BUILTIN_RIPGREP=0

Risks

  • Disabling built-in ripgrep may slightly reduce grep performance or affect ripgrep-dependent features like @-mention file suggestions
  • This is a workaround, not a permanent fix — the official fix is upgrading to v2.0.27+
  • System-installed ripgrep is used as fallback; if ripgrep is not installed, grep performance may degrade significantly

Verification

  • Step 1: Check if ripgrep is available: `which rg 2>&1; echo exit=$?` → expect: path to rg or 'rg not found'. If rg is not installed, the fallback grep will be used which is slower but functional.
  • Step 2: Run `export USE_BUILTIN_RIPGREP=0 && claude --version 2>&1; echo exit=$?` → expect stdout: version number, exit code 0. This confirms the env var does not prevent Claude Code from starting.
  • Step 3: Run `echo $USE_BUILTIN_RIPGREP` → expect: '0'
  • Step 4: In a Claude Code session launched with USE_BUILTIN_RIPGREP=0, type '@some_directory' in a prompt → expect: Claude should respond normally without error
✓ 0 verified✕ 0 failed

Use Relative Paths Instead of @ References (Workaround)

risk: lowgithubpublished

The bug is specifically triggered by '@' directory references. Using standard relative paths (./ or ../) avoids triggering the broken ripgrep @-reference handler while still allowing Claude Code to access the same files. This workaround is useful when upgrading is not immediately possible.

  1. Instead of '@docs/reference/' in your prompt, use './docs/reference/' or the full absolute path
  2. For individual files, @ references to files (not directories) usually work — test first with a single file before using directory references
  3. If Claude Code needs context from a directory, use './path/to/dir' in your prompt instead of '@dir'

Commands

# Instead of: @docs/reference/
# Use: ./docs/reference/ or /absolute/path/to/docs/reference/
# Verify path exists before using: ls ./docs/reference/ 2>&1; echo exit=$?

Risks

  • Claude Code may behave slightly differently with relative paths vs @ references — @ references provide richer context with file type detection
  • Some Claude Code features that depend on @ reference parsing may be unavailable with relative paths

Verification

  • Step 1: Run `ls ./path/to/dir 2>&1; echo exit=$?` → expect exit code 0 (directory exists). If exit code is non-zero, the path is invalid — correct it.
  • Step 2: In a Claude Code session, type a prompt containing './relative/path/to/dir' instead of '@dir' → expect: Claude should process the reference and respond normally without 'No assistant message found'
✓ 0 verified✕ 0 failed

Agent Decision Tree: Diagnose and Choose the Right Fix

risk: lowagentpublished

When an AI agent encounters 'No assistant message found' in a Claude Code session, use this decision tree to identify the root cause and apply the correct fix. This covers version checking, workaround selection, and fallback paths.

  1. Step 1 — Version Check: Run `claude --version`. If version is 2.0.22–2.0.26 → upgrade (Solution 1). If version ≥ 2.0.27 → the bug is fixed; the error has a different cause (check network/API).
  2. Step 2 — If upgrade is blocked (no npm access, corporate policy): Try the USE_BUILTIN_RIPGREP workaround (Solution 3).
  3. Step 3 — If the workaround also fails (e.g., ripgrep needed for other features): Fall back to using relative paths instead of @ references (Solution 2).
  4. Step 4 — If error persists after upgrade: Run `ANTHROPIC_LOG=debug claude -p 'test' 2>&1 | grep -i 'ripgrep\|assistant message\|tool_result'` to check if the error is a new variant or a different root cause.

Commands

claude --version
ANTHROPIC_LOG=debug claude -p 'test' 2>&1 | grep -iE 'ripgrep|assistant message|tool_result'

Risks

  • This is a diagnostic guide, not a standalone fix — it directs the agent to the correct solution

Verification

  • Step 1: Run `claude --version 2>&1` → expect: version number. If 2.0.22–2.0.26, decision tree says 'upgrade'. If ≥ 2.0.27, decision tree says 'different root cause'.
  • Step 2: Run `npm install -g @anthropic-ai/claude-code 2>&1; echo exit=$?` → expect exit code 0 if npm is available. If non-zero, decision tree says 'USE_BUILTIN_RIPGREP workaround'.
✓ 0 verified✕ 0 failed

Upgrade to Claude Code v2.0.27 or Later (Official Fix)

risk: lowofficialpublished

Anthropic fixed the built-in ripgrep crash in v2.0.27 (October 24, 2025). Staff member wolffiex confirmed 'We should have this fixed in today's release' and community testing confirmed v2.0.27 resolves the issue. Simply upgrade to the latest version to resolve the issue permanently.

  1. Check your current version: claude --version
  2. If version is between 2.0.22 and 2.0.26, upgrade: npm install -g @anthropic-ai/claude-code@latest
  3. Verify the upgrade: claude --version should show 2.0.27 or later
  4. Test with an @ directory reference to confirm the error no longer occurs

Commands

claude --version
npm install -g @anthropic-ai/claude-code@latest
npm view @anthropic-ai/claude-code version

Risks

  • Upgrading may introduce other changes from versions between your current version and latest (current latest: v2.1.177 as of June 2026)

Verification

  • Step 1: Run `claude --version 2>&1; echo exit=$?` → expect stdout containing version number (e.g., '2.0.27' or higher), exit code 0. If version is 2.0.22–2.0.26, proceed to Step 2.
  • Step 2: Run `npm view @anthropic-ai/claude-code version 2>&1; echo exit=$?` → expect stdout: version number (e.g., '2.1.177'), exit code 0. This confirms npm registry is reachable.
  • Step 3: Run `npm install -g @anthropic-ai/claude-code@latest 2>&1; echo exit=$?` → expect exit code 0. If exit code is non-zero, check network/npm configuration.
  • Step 4: Run `claude --version 2>&1; echo exit=$?` → expect stdout: version '2.0.27' or higher, exit code 0. If still showing 2.0.22–2.0.26, the global npm bin may not be in PATH — check with `which claude`.
  • Step 5: Create test directory and verify fix: `mkdir -p /tmp/claude-test && echo 'test content' > /tmp/claude-test/test.txt && claude -p 'list files in @/tmp/claude-test' 2>&1; echo exit=$?` → expect: Claude lists the file without 'No assistant message found' error, exit code 0
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "9513c942-fc91-4885-9934-c4592bf2c4b1",
  "slug": "fix-claude-code-no-assistant-message-found-error-when-using-directory-references-on-macos-windows-and-linux-bq019h",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-no-assistant-message-found-error-when-using-directory-references-on-macos-windows-and-linux-bq019h"
}
← Back to all issuesPowered by CodeKB