Troubleshooting and limits

This page lists the symptoms users hit most, what causes each, and the fix. It describes the main branch; for release 0.3.1, also check Release 0.3.1 and main.

First principles

Almost every surprise has one of three causes:

1. The file is not a candidate. An ignore rule, the hidden filter, a glob, a type or a depth limit removed it, or the index believes it lacks the text.
2. The index is out of date. A --ttl window skipped the sweep, or a file changed without changing its modification time or size.
3. The search needs every file. The answer is right but slow, because the pattern or a flag defeats narrowing.

glep --no-index separates the first two. It walks the tree live with the same ignore and hidden rules and never opens the index. If glep PATTERN and glep --no-index PATTERN disagree, the index is stale: run glep index. If they agree and a file is still missing, a filter or rule excluded it.

A file I just edited is not found

• You passed --ttl. Inside the window the sweep is skipped, so new and changed files are invisible. Run the query without --ttl.
• The file’s modification time and size did not change. Some copy tools preserve both. The sweep trusts them, so the index keeps the old contents. Run glep index.

A file I expect is missing from the results

• It is ignored. .gitignore applies even outside a git repository, unlike ripgrep’s default. Add --no-ignore to include ignored files, or --require-git to apply git rules only inside a repository.
• It is hidden. Dot-prefixed files and directories are left out by default. Add --hidden.
• A positive -g glob did not bring it back. Globs filter the indexed files, which never include ignored ones. Add --no-ignore.
• It is binary. A file with a NUL byte in its first 64 KiB prints nothing by default, as in ripgrep. Use -a to search it as text or --binary to get a binary file matches notice.
• It lives in .git or .glep. Those are never searched, even under -uu.
• You ran from a subdirectory. With no path argument, the search covers only the current directory.

--files src prints nothing

With --files, the first positional argument is a glob. glep --files src lists files named src. Pass a glob first: glep --files '**' src.

Messages and what to do

• glep: another glep holds the index lock (from glep index): another glep process is writing the index, possibly the background build a first query started. Wait and retry. Queries keep working meanwhile.
• glep: index unreadable (...); rebuilding: the index was corrupt or from another version. glep is rebuilding it; nothing to do.
• glep: postings blob corrupt; treating trigram as empty (run: glep index): part of the postings file failed to decode, so narrowing may miss files. Run glep index.
• glep: bulk sweep failed (...), falling back to walker sweep (macOS): the fast sweep failed and the portable walker took over. Results are correct; that query was slower.
• glep: No files were searched, which means glep probably applied a filter you didn't expect. (exit 2): with no path argument, the filters left no file at all. Check -g, -t, -T and -d, and run with --debug.
• glep: <path>: No such file or directory (os error 2) (exit 2): a path operand does not exist. The other operands are still searched.
• glep: a pattern is required (or --files): no pattern was given.

Exit code 2 although results printed

glep, like ripgrep, keeps searching after a per-file error (an unreadable file or directory, a missing operand, a failing --pre command) and exits 2 at the end. The messages are on stderr. --no-messages hides them but not the exit code. With -q, a match still exits 0.

A search is as slow as ripgrep

Use GLEP_TIMING=1 to see where the time goes (see Indexing and freshness). Common causes:

• The pattern cannot be narrowed. No literal of three bytes or more, an alternation with a short branch, or a flag such as -v, --passthru, -c --include-zero, --pre or a non-UTF-8 -E. Add a longer literal if the question allows it.
• The pattern is very common. When most files contain it, most files are searched.
• A live-scan flag is set. --no-ignore, -u, -L, --one-file-system, the --no-ignore-* family and --no-index never use the index.
• It is the first query on a large tree. It answers with a full scan while the index builds in the background.
• The sweep dominates. On large trees, most of a warm query is the freshness sweep. Use --ttl for read-only bursts.
• On macOS, an in-tree .ignore or .rgignore file. It sends the sweep to the slower portable walker, without a warning. GLEP_TIMING shows a large sweep_walk.

Output is colored

On a terminal, glep colors output by default, as ripgrep does. Piped output has no color. Use --color never to turn it off everywhere.

The agent hook does nothing

• glep is not on the PATH the hook sees.
• The session’s working directory has no .glep/. The hook does not look in parent directories, so run glep index in the directory the agent starts in.
• python3 is missing, or the hook entry is not in the settings file.
• The call was a Grep in content mode with -n: false. The hook leaves those to the built-in tool on purpose.

See Using glep with Claude Code and Using glep with Cursor.

Results differ from ripgrep

A few differences are deliberate, such as path spelling under ./ operands and .gitignore outside git repositories. They are listed in Output formats. Anything else is a bug; the project treats any byte difference from ripgrep as one.

Limits

• One index covers one tree. There is no machine-wide or multi-repository index.
• glep never reads standard input as a file to search. -f - reads patterns from it.
• -z decompresses gzip only.
• Files over the size cap (default 1 MiB) are not indexed. They are searched live on every query, so many large files make queries slower.
• Freshness is judged by modification time and size only.
• The index takes disk space: about 10% of the corpus on the Linux kernel tree.
• The background first build and the --ttl window are per tree, not per process: every glep on the tree shares them.
• The getattrlistbulk sweep and the listing cache are macOS only. Windows always builds the first index inline.
• After an upgrade that changes the index format, the first query rebuilds the index once.