> ## Documentation Index > Fetch the complete documentation index at: https://docs.entire.com/llms.txt > Use this file to discover all available pages before exploring further. # entire-graph Troubleshooting > Fix entire-graph install, activation, adoption, cache, and coverage problems. Use this page when entire-graph is not installed, not being used by your agent, or not returning what you expect. ## Install and Setup > **`entire graph` prints the main Entire help instead of running** > > The plugin is not installed. The CLI does not recognize `graph` as a command, so it falls back to its own help output. > > ```bash theme={null} > entire plugin install graph > entire graph version > ``` > > Confirm it landed: > > ```bash theme={null} > entire plugin list > ``` > **Queries fail with a `git cat-file --batch-command` error** > > Your Git is older than 2.36. entire-graph uses the single-session object protocol that Git 2.36 added to check an object's type before reading its contents, so queries cannot run without it. The error names the requirement: > > ```text theme={null} > git cat-file --batch-command unavailable (Git 2.36 or newer required) > ``` > > Check your version, and upgrade Git if it is older: > > ```bash theme={null} > git --version > ``` > > If several Git installations are present, confirm which one entire-graph resolves on your `PATH`: > > ```bash theme={null} > command -v git > ``` > **`entire graph version` prints `dev`** > > You are running an unversioned local build, usually from `scripts/install-local.sh` or a manual `go build`. That is expected during development and not expected otherwise. > > Reinstall a released build: > > ```bash theme={null} > entire plugin install graph --force > ``` > **`plugin install` refuses the download** > > Releases are verified against the release's `checksums.txt`. A release that publishes no checksums is refused. > > If you trust the source and understand the tradeoff, pass `--allow-unverified`. Otherwise check that you have the right repository URL. > > Installing from a URL that is not in the plugin index also asks for confirmation. In a script or CI, add `--yes`. > **`init-agents` fails before writing anything** > > `init-agents` checks both instruction files before its first write, so a failure means nothing was changed. > > Two things cause it. First, `AGENTS.md` or `CLAUDE.md` is not a regular file. A directory, pipe, socket, or device is rejected, and the error names the type it found. Second, a file has a broken marker layout. Each file must contain either zero entire-graph marker tokens, or exactly one begin marker followed by one end marker. > > Marker tokens count even inside code fences, examples, or HTML comments, because they make the replacement range ambiguous. To recover: > > 1. Back up `AGENTS.md` and `CLAUDE.md`. > 2. Replace any non-regular target with a regular file, or move it aside. > 3. Reword any stray marker strings that appear in examples or comments. > 4. Rerun `entire graph init-agents --repo .`. > **Your edits to `.entire/graph-agent.md` disappeared** > > That file is generated, and it is regenerated in full on every successful `init-agents` run. Manual edits there are not preserved by design. > > Put your own instructions in `AGENTS.md` or `CLAUDE.md`, outside the `` and `` markers. Everything outside those lines is left alone. > **Remove entire-graph from a repository** > > Delete `.entire/graph-agent.md`, then remove the section entire-graph manages in `AGENTS.md` and `CLAUDE.md`. You can delete `.entire/` or either instruction file if it is otherwise empty. > > To also remove entire-graph from your machine, run: > > ```bash theme={null} > entire plugin remove graph > ``` ## Your Agent Is Not Using entire-graph > **The agent greps instead of running `entire graph search`** > > This is the most common problem, and it has three usual causes. > > **The session predates activation.** An agent session that was already open never read the new files. Quit it and start a fresh session in the repository. > > **The guide is not reaching the agent.** Confirm the generated guide matches your installed build: > > ```bash theme={null} > diff <(entire graph agent-guide) .entire/graph-agent.md > ``` > > Empty output means they match. Then check that the managed block is present in the instruction file your agent actually reads. > > **Your agent does not resolve `@` imports.** Claude Code loads `CLAUDE.md` at session start and resolves the import. Other clients may treat the block as plain text, in which case they still get a written instruction to read `.entire/graph-agent.md`, but whether they follow it depends on the client and the model. Verify the behavior rather than assuming it. > **`CLAUDE.md` seems to have the wrong block** > > If a distinct `CLAUDE.md` already contains a live standalone import that resolves to your root `AGENTS.md`, entire-graph deliberately puts only an inheritance notice in its `CLAUDE.md` block, so the guide is not imported twice: > > ```markdown theme={null} > > > > ``` > > Add or remove that `AGENTS.md` import and rerun `init-agents` to switch between the two layouts. Import detection only recognizes standalone paths. A mention inside inline code, a code fence, or an HTML comment does not count, and anything ambiguous keeps the direct pointer instead of assuming inheritance. ## Queries Are Slow > **Every query rebuilds the index** > > entire-graph reuses a cached snapshot only when the working tree is clean. Any dirty file that entire-graph can index turns reuse off for the whole repository until the tree is clean again. > > Clean tree: > > ```text theme={null} > Index: cache-hit (69ms) | Query: 0ms | Total: 70ms > ``` > > One uncommitted change to an indexable file such as `go.mod`: > > ```text theme={null} > Index: cache-miss (782ms) | Query: 0ms | Total: 782ms > ``` > > Check what is dirty: > > ```bash theme={null} > git status --short > ``` > > Extensionless files and root dependency manifests like `go.mod` and `package.json` all count. Dirty files entire-graph cannot index, such as a `.bin`, do not. > > The most common version of this is forgetting to commit the three activation files after running `init-agents`. > **You ran `index` but queries still miss the cache** > > Two defaults have to line up, and out of the box they do not. > > `index` only warms committed-tree queries, and the interactive commands read the working tree unless you pass `--head`. `index` also defaults to `--profile full` while plain `search` defaults to `--profile fast`, and the profile is part of the cache key. > > So a default `index` run does not warm a default `search`. Match both: > > ```bash theme={null} > entire graph index --repo . --profile fast > entire graph search --repo . --head --profile fast --query "..." > ``` > > Changing `.graphignore` also selects a different cache entry. > **`def` and `explain` never seem to cache** > > Unlike the other query commands, `def` and `explain` only cache when `--cache-dir` or `ENTIRE_PLUGIN_DATA_DIR` is set. Set one of them if you are calling those two repeatedly. ## Results Are Not What You Expected > **A symbol name is ambiguous** > > entire-graph lists every definition it found and prints the exact selector for each one, so you can copy the one you want: > > ```text theme={null} > "Match" matches 9 definitions; all are listed, the first 2 with source. > - Router.Match (mux.go:151) [method] --symbol Router.Match --file mux.go --line 151 > - routeRegexp.Match (regexp.go:189) [method] --symbol routeRegexp.Match --file regexp.go --line 189 > - Route.Match (route.go:47) [method] --symbol Route.Match --file route.go --line 47 > ``` > > You can also address a definition directly with `--symbol FILE:LINE`. > **No symbols matched** > > ```text theme={null} > No symbols matched "NopeNotHere". Run `entire graph search --query "NopeNotHere"` to find the name, or `entire graph symbols --repo .` for the full definition inventory. > ``` > > Usually the name is spelled differently in source, or it lives in a language that is inventory only. Start with `search`, which takes plain language rather than an exact symbol. > **`impact` reports fewer callers than really exist** > > Expected, and worth internalizing. Static analysis is heuristic, not a compiler. Calls through interfaces, reflection, dynamic dispatch, and generated or runtime-wired code can be missed or left unresolved. > > Dependent counts are guidance for inspection, not facts. Treat graph output as evidence to check against source. Relation edges carry `resolution` and `confidence` fields rather than a completeness promise. > **`search` says LOW CONFIDENCE** > > entire-graph tells you when the ranking did not actually choose, for example when the top two results are effectively tied: > > ```text theme={null} > LOW CONFIDENCE: top score 34.3 and ranks 1 and 2 are tied (0.0190 apart) - the ranking did not choose. This repo may not contain what you asked for; verify before editing. > ``` > > Rephrase the query to be more specific, or accept that the repository may not contain what you asked for. Do not edit on a low-confidence hit without reading the source first. > **A language returns files but no relationships** > > Coverage comes in two tiers. Semantic languages are parsed for relationships; inventory-only filetypes give you file and symbol structure but no call or type analysis. See [What entire-graph Might Not Find](/guides/graph/how-graph-works#what-entire-graph-might-not-find) for which languages are in each tier. > > Check what your build supports: > > ```bash theme={null} > entire graph capabilities --json > ``` > **Files are missing, or coverage says degraded** > > Files the parser cannot handle surface as machine-readable partial failures rather than vanishing silently. Look at the `partial_failures` and `warnings` fields in JSON output, or the coverage line in agent format. > > Vendored and generated sources that are tracked in Git are the usual cause, since they show up as `E_FILE_TOO_LARGE` or `E_PARSE_ERROR`. Exclude them with a `.graphignore` at the repository root, which uses gitignore syntax and applies on top of `.gitignore`. ## Checking the Environment `entire graph doctor` reports the resolved repository, the Entire environment variables, whether the plugin data directory is writable, and confirms no network egress: ```text theme={null} ENTIRE_CLI_VERSION=0.10.1 ENTIRE_REPO_ROOT=/path/to/repo ENTIRE_PLUGIN_DATA_DIR=/Users/you/.local/share/entire/plugins/data/graph no_egress=true plugin_data_dir=writable repo_root=/path/to/repo ``` If a script built a command line against a different version, check it before running anything: ```bash theme={null} entire graph doctor --assert "search --profile full --top-k 10 --format text" ``` An unaccepted flag is named explicitly, without reading the repository or building an index: ```text theme={null} search does not accept --nope in entire-graph v0.4.0: this binary may be older than the caller that built the command line; run "entire graph search --help" for the flags it does accept (unexpected: --nope) ``` ## Continue With > **[Install and Enable entire-graph](/guides/graph/set-up-graph)** > > Install the plugin and turn it on for a repository. > **[entire-graph CLI Reference](/cli-reference/graph)** > > Every query, analysis, and export command. > **[plugin](/cli-reference/plugin)** > > Install, upgrade, and remove plugins. > **[entire-graph Issues](https://github.com/entireio/entire-graph/issues)** > > Report a problem with entire-graph.