Troubleshooting

Graph not found

If a command fails with a missing graph error, run a build from the repository root and confirm that ontoly-output is readable. Use ontoly doctor for a full readiness check.

pnpm exec ontoly build .
pnpm exec ontoly doctor
ls ontoly-output/SoftwareGraph.json

Ambiguous query

If a search returns too many or too few results, refine the query. Search first to see candidates, then use a stable node ID for precise commands. Do not increase traversal depth to compensate for unresolved intent.

ontoly search "auth"              # broad search
ontoly search "auth" --category symbol  # narrow by category
ontoly inspect service:AuthService  # use stable ID

Partial results

A PARTIAL status means a traversal budget was exhausted — time, depth, nodes, or edges. Inspect the diagnostics to understand which budget was hit. Narrow the query or increase the specific budget rather than removing limits entirely.

• Check the visited count in the response
• Inspect which budget was exhausted (time, depth, nodes, edges)
• Narrow the query to a more specific starting node
• Increase the specific budget with --max-time-ms, --max-nodes, etc.
• Use --mode direct for the narrowest impact analysis

History unavailable

History-based commands (ownership, churn, hotspots, cochanges) require Git. Confirm Git is installed, the repository has commit history, and the process can read git output. Shallow clones may limit history analysis.

git log --oneline -5          # verify history exists
git rev-parse --git-dir       # verify git repo
ontoly history inspect .      # inspect history state

MCP connection issues

The MCP server uses a line-JSON stdin/stdout protocol. It does not implement the standard MCP initialize handshake. Do not register it as a standard MCP server in tools that expect the initialize/initialized flow. Use it as a stdio server configured to launch ontoly mcp.

• Build the graph before starting MCP
• Run from the repository root (same directory as ontoly-output)
• Use ontoly mcp --list to verify capabilities load
• Check that the process can read ontoly-output/SoftwareGraph.json
• If using from an IDE, configure as a stdio command, not a network server

Build failures

If the build fails or produces warnings, run ontoly doctor for a readiness check. Common issues include missing TypeScript configuration, unresolvable imports, and unsupported language features.

ontoly doctor
ontoly build . --verbose    # detailed build output
ontoly validate repository  # run validation checks