Troubleshooting & FAQs
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance for resolving common issues encountered when deploying, indexing, and querying codebases with Arbor. It covers system health diagnostics, parser limitations, and communication failures between the CLI, GUI, and Model Context Protocol (MCP) bridge.
Arbor operates as a local-first impact analysis engine, which introduces specific points of failure related to file system permissions, port availability, and language-specific AST parsing.
System Health and Diagnostics
The arbor check-health command is the primary diagnostic tool for verifying the local environment. It performs a suite of checks to ensure all required components are accessible and the workspace is correctly initialized.
Health Check Sequence
The following diagram illustrates the diagnostic flow performed by the CLI:
Common Health Issues
| Component | Symptom | Resolution |
|---|---|---|
| Workspace | No Cargo.toml found | Run commands from the root of a Rust project or initialized workspace. |
| Networking | Port 8080 in use | Close existing SyncServer instances or identify other processes using port 8080. |
| Initialization | Arbor not initialized | Execute arbor init to create the required .arbor/ configuration directory. |
Sources: crates/arbor-cli/src/commands.rs:452-490, crates/arbor-cli/src/commands.rs:24-40
Indexing and Parser Failures
Users may encounter scenarios where arbor index completes but results in an empty graph or missing symbols.
Symbol Missing from Graph
If a specific function or class is missing, verify the following:
- .gitignore Constraints: Arbor respects
.gitignorerules. If a file is ignored by Git, it is ignored by the indexer. - Empty Files: Arbor skips files containing only comments or imports (except for Python
__init__.pywhich is handled silently). - Language Support: Ensure the file extension is supported (e.g.,
.rs,.ts,.py,.java,.cs). - Dynamic Dispatch: Calls made via reflection or
evalmay not be statically resolvable, leading to "Low" confidence scores or missing edges.
Sources: README.md:214-228, crates/arbor-cli/src/commands.rs:69-74, crates/arbor-cli/src/commands.rs:327-332
Fuzzy Matching and Typos
Arbor v1.5+ includes Jaro-Winkler similarity matching to assist when exact symbol lookups fail. If an exact match is not found, the system provides suggestions based on name similarity and relevance scores.
// Relevance scoring logic in suggest_similar_symbols
let relevance = if name_lower == target_lower {
100 // Exact name match
} else if id_lower.ends_with(&format!("::{}", target_lower)) {
80 // Exact suffix match
} else if name_lower.starts_with(&target_lower) {
60 // Starts with
} else if similarity > 0.75 {
30 // Fuzzy match
}
Sources: crates/arbor-cli/src/commands.rs:777-802
Visualizer and GUI Issues
The Arbor Visualizer requires specific environmental setups depending on whether it is running as a bundled executable or in development mode.
Execution Failures
The CLI attempts to launch the visualizer in a specific priority order:
- Bundled Executable: Located in
arbor_visualizer/relative to the binary. - Flutter Dev Mode: Located in the
visualizer/source directory.
GUI Privacy and "Spoiler Mode"
By default, the GUI hides file paths to facilitate clean screenshots for PRs. If file paths appear as ████████████████, this is the intended "Spoiler Mode." Users must click the box to reveal the path.
Sources: crates/arbor-gui/src/app.rs:65-72, crates/arbor-gui/src/app.rs:242-269
AI Bridge (MCP) Troubleshooting
The Model Context Protocol bridge (arbor bridge) communicates over stdio. Logging to stdout within custom integrations will corrupt the JSON-RPC stream.
Protocol Failures
- JSON-RPC Errors: Methods like
analyze_impactorfind_pathreturn standard JSON-RPC error codes (e.g.,-32601for Method not found). - Node Resolution: If an AI agent provides a name that exists in multiple files, the bridge may fail to resolve the correct node unless the Fully Qualified Name (FQN) is used.
- Spotlight Failures: If the visualizer does not move when the AI queries a node, ensure the
SyncServeris running on the correct port and the visualizer is connected tows://127.0.0.1:8080.
Sources: crates/arbor-mcp/src/lib.rs:88-150, crates/arbor-mcp/src/lib.rs:350-380, extensions/arbor-vscode/package.json:62-65
Frequently Asked Questions (FAQ)
Q: Why is my impact analysis confidence "Low"?
A: This usually occurs if the node has few static callers detected. It may be an entry point (API/CLI) or invoked dynamically via reflection, dependency injection, or callbacks.
Sources: crates/arbor-cli/src/commands.rs:608-615
Q: Can I run Arbor in a Docker container?
A: Yes. Use the --headless flag with arbor serve to start the server without attempting to launch a local browser or GUI, allowing it to bind to 0.0.0.0.
Sources: crates/arbor-cli/src/commands.rs:135-165
Q: How do I resolve Tree-sitter returned no tree errors?
A: This indicates a catastrophic parsing failure. Verify that the file content is not corrupted and that the file size does not exceed memory limits. The system handles standard syntax errors gracefully by extracting partial ASTs.
Sources: crates/arbor-core/src/parser_v2.rs:159-165
Q: What do the impact severity levels mean?
- Direct: 1 hop away; changing the target will break this node immediately.
- Transitive: 2-3 hops away; logic changes ripple through intermediate nodes.
- Distant: 4+ hops away; potential side effects in far-reaching modules.
Sources: CHANGELOG.md:7-12, crates/arbor-cli/src/commands.rs:723-745
This documentation concludes the technical overview of Arbor's troubleshooting procedures. For persistent issues, refer to the GitHub Discussions.