Troubleshooting

The command is not found#

Confirm that the executable is installed and its directory is on PATH. Open a new terminal after changing PATH. An editor launched earlier may still have the old environment; restart it or configure the full executable path.

arbor --version
arbor --help

If you used npx, invoke the npm wrapper with its full prefix, or install the standalone binary. See installation for the supported release paths.

No files or symbols appear#

Check the directory first. Run these commands at the source project's root, then inspect the reported files.

arbor setup
arbor status --files
arbor map

Make sure the source files use supported language extensions. Check repository ignore rules and the generated Arbor configuration if an expected file is missing. A dependency or generated output directory is not a useful substitute for the project's source.

A symbol cannot be found#

Search a shorter, literal part of the name and inspect the defining file. Replace both examples with your own symbol and path.

arbor query parse --limit 20
arbor file-graph src/parser.py

If you previously filtered test files with --exclude-test, retry without that filter. Check the definition's file and use its qualified name or node ID where supported to avoid selecting another symbol with the same name.

Results look stale or surprising#

arbor --version
arbor index --no-cache
arbor status

A full rebuild removes cached graph data from the equation. Results can still differ across engine versions, and a fresh graph can still contain incomplete relationships. Review the documented limits, especially for inherited methods and runtime imports.

If arbor bridge is running for the project, the CLI does not refresh the graph itself. After a checkout or commit it prints note: the graph was built at … but HEAD is now …. The bridge catches up on its own; to refresh now, stop it and run arbor index.

If a Git impact report is empty, check what it compared. With a clean working tree, arbor diff reports No modified files detected against HEAD. Use --base main for work you have already committed on a branch.

MCP tools do not appear#

1. Verify the executable path from the editor's environment.
2. Check that the bridge points to the intended project and that arbor setup completed there.
3. Validate the config: Cursor uses mcpServers; VS Code uses servers.
4. Reload the server and inspect the client's MCP output for the actual error.

If a terminal-launched bridge appears idle, it may simply be waiting for protocol messages. Use a configured MCP client to test tool discovery. The MCP guide includes complete configurations.

No receipt after a Claude Code turn#

1. Run arbor --version in the shell Claude Code uses. The hooks run whichever arbor comes first on PATH, and an older build fails with unrecognized subcommand 'receipt'.
2. Confirm the project is a git repository. In v3.0.3, receipts record nothing outside one and give no reason.
3. Open .claude/settings.json, or ~/.claude/settings.json if you used --global, and look for arbor receipt begin under UserPromptSubmit and arbor receipt end --hook under Stop. Running arbor hook claude again adds any that are missing.
4. A turn that changes no files, or only generated files and .arbor/, writes no receipt. arbor receipt list shows what was saved.

The receipts guide lists the other known problems in v3.0.3.

Report a reproducible issue#

Open an issue on GitHub with the Arbor version, install channel, operating system, exact command, and error text. For a graph mismatch, include a small source example, the relationship you expected, and the actual result.

Remove secrets and private source before sharing logs or an example. A small public reproduction is easier to verify than a screenshot of a large graph.