> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/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

<AccordionGroup>
  <Accordion title="`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
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="`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
    ```
  </Accordion>

  <Accordion title="`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`.
  </Accordion>

  <Accordion title="`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 .`.
  </Accordion>

  <Accordion title="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 `<!-- entire-graph:begin -->` and `<!-- entire-graph:end -->` markers. Everything outside those lines is left alone.
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

## Your Agent Is Not Using entire-graph

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="`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}
    <!-- entire-graph:begin -->
    <!-- Entire Graph instructions are inherited through AGENTS.md. -->
    <!-- entire-graph:end -->
    ```

    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.
  </Accordion>
</AccordionGroup>

## Queries Are Slow

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="`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.
  </Accordion>
</AccordionGroup>

## Results Are Not What You Expected

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="`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.
  </Accordion>

  <Accordion title="`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.
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install the plugin and turn it on for a repository.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Every query, analysis, and export command.
  </Card>

  <Card title="plugin" icon="plug" href="/cli-reference/plugin">
    Install, upgrade, and remove plugins.
  </Card>

  <Card title="entire-graph Issues" icon="github" href="https://github.com/entireio/entire-graph/issues">
    Report a problem with entire-graph.
  </Card>
</CardGroup>