Debugging with GitNexus
When to Use
"Why is this function failing?"
"Trace where this error comes from"
"Who calls this method?"
"This endpoint returns 500"
Investigating bugs, errors, or unexpected behavior
Workflow
1. gitnexus_query({query: ""}) → Find related execution flows
2. gitnexus_context({name: ""}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
If "Index is stale" → run
npx gitnexus analyze
in terminal.
Checklist
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] gitnexus_query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] gitnexus_context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] gitnexus_cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
Debugging Patterns
Symptom
GitNexus Approach
Error message
gitnexus_query
for error text →
context
on throw sites
Wrong return value
context
on the function → trace callees for data flow
Intermittent failure
context
→ look for external calls, async deps
Performance issue
context
→ find symbols with many callers (hot paths)
Recent regression
detect_changes
to see what your changes affect
Tools
gitnexus_query
— find code related to error:
gitnexus_query({query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
gitnexus_context
— full context for a suspect:
gitnexus_context({name: "validatePayment"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
gitnexus_cypher
— custom call chain traces:
MATCH
path
=
(
a
)
-
[
:
CodeRelation
{
type
:
'CALLS'
}
*
1
..
2
]
->
(
b
:
Function
{
name
:
"validatePayment"
}
)
RETURN
[
n
IN
nodes
(
path
)
|
n
.
name
]
AS
chain
Example: "Payment endpoint returns 500 intermittently"
1. gitnexus_query({query: "payment error handling"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. gitnexus_context({name: "validatePayment"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout