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. query({search_query: "<error or symptom>"})            → Find related execution flows

2. context({name: "<suspect>"})                    → See callers/callees/processes

3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow

4. cypher({statement: "MATCH path..."})                 → Custom traces if needed

If "Index is stale" → run node .gitnexus/run.cjs analyze in terminal.

Checklist

- [ ] Understand the symptom (error message, unexpected behavior)

- [ ] query for error text or related code

- [ ] Identify the suspect function from returned processes

- [ ] context to see callers and callees

- [ ] Trace execution flow via process resource if applicable

- [ ] cypher for custom call chain traces if needed

- [ ] Read source files to confirm root cause

Debugging Patterns

Tools

query — find code related to error:

query({search_query: "payment validation error"})

→ Processes: CheckoutFlow, ErrorHandling

→ Symbols: validatePayment, handlePaymentError, PaymentException

context — full context for a suspect:

context({name: "validatePayment"})

→ Incoming calls: processCheckout, webhookHandler

→ Outgoing calls: verifyCard, fetchRates (external API!)

→ Processes: CheckoutFlow (step 3/7)

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

trace — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining context hops:

trace({ from: "processCheckout", to: "fetchRates" })

→ status: ok, hopCount: 3

→ hops: processCheckout → validatePayment → verifyCard → fetchRates

→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)

When no path exists, trace reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).

Example: "Payment endpoint returns 500 intermittently"

1. query({search_query: "payment error handling"})

   → Processes: CheckoutFlow, ErrorHandling

   → Symbols: validatePayment, handlePaymentError

2. 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