Troubleshooting

Quick Symptom Table

Symptom	Likely cause	Action
semantic/hybrid errors or weak results	missing/stale index or embeddings setup	run cgrep index, then verify embeddings config
results look incomplete from subdirectories	scope mismatch	pass explicit scope: -p <path>
agent output is too large	payload budget too loose	use --budget tight or --profile agent
semantic/hybrid returns nothing without clear error	embeddings/index not ready	rebuild with cgrep index --embeddings auto
keyword works but semantic/hybrid fails	expected behavior without index	keyword can scan fallback; semantic/hybrid require index
Error: Search query cannot be empty	query is empty/whitespace (including --regex "")	pass a non-empty query string
Error: Path cannot be empty from read	missing path argument	pass a valid file path to cgrep read <path>
error: unexpected argument '<path>' found when query starts with -	-- separator was placed before options/path	put flags/path first, then -- (e.g., cgrep search -p src -- --help)
invalid value 'codex' for '<HOST>' from mcp install	codex is not an MCP host value for this command	use cgrep agent install codex for Codex, or choose a host from cgrep mcp install --help
invalid search mode 'auto' or invalid value 'auto' for '--mode <MODE>' in CLI search	auto/default is MCP compatibility behavior, not a CLI engine mode	for CLI use --mode keyword|semantic|hybrid; use --profile agent|human|fast for retrieval defaults
MCP client sends mode=auto and behavior seems unclear	auto means “use the current default search behavior”	keep mode for engine choice, and use profile=agent if you want agent-friendly payload defaults
MCP tool call timed out or said to retry with narrower scope	request scope/payload is still too broad	rescope with path → glob → changed → file_type, then lower limit / context
MCP tool call output exceeded the cap	too many matches or too much context	use profile=agent, reduce limit / context, or narrow scope with path / glob / changed / file_type
MCP results still look stale after large edits	long-lived session still needs a fresh request lifecycle	restart the MCP session/client after narrowing scope, then retry
GLIBC_2.39 not found on Linux after release install	host glibc is older than the downloaded Linux asset	upgrade to the latest release (Linux builds are now pinned to Ubuntu 22.04 / glibc 2.35 baseline) or install from source (cargo install --path .)

Fast Recovery Sequence

cgrep index
cgrep search "sanity check" -m 5
cgrep search "sanity check" --mode keyword -m 5
cgrep --format json2 --compact status
CGREP_BIN=cgrep bash scripts/validate_all.sh

Search / MCP Rescope Checklist

When a request is noisy, slow, or too large, narrow it in this order:

1. -p <path> / MCP path
2. --glob <pattern> / MCP glob
3. -u [rev] / MCP changed
4. -t <lang> / MCP file_type
5. lower limit / context
6. switch to --profile agent (CLI) or profile=agent (MCP) for smaller payload defaults

Examples:

cgrep s "retry budget" -p src/ --glob "*.rs" -u HEAD -t rust
cgrep s "retry budget" -p src/ --profile agent -B tight --format json2 --compact

Search mode vs profile

Use this rule of thumb:

• mode = engine selection
• keyword
• semantic
• hybrid
• profile = retrieval defaults / output shape
• human
• agent
• fast

Examples:

# CLI: explicit engine
cgrep s "auth flow" --mode keyword

# CLI: agent-friendly retrieval defaults
cgrep s "auth flow" --profile agent -B tight --format json2 --compact

# Usage lookup mode is separate from search --mode
cgrep r AuthService -M auto

For MCP clients, mode=auto and mode=default are accepted as compatibility aliases for the default search behavior. They do not introduce a separate search engine mode.