Debugging with GitNexus

When to Use This Skill

Use the Debugging skill when you need to:

Trace where an error originates
Understand why a function is failing
Find who calls a problematic method
Investigate unexpected behavior
Debug 500 errors or crashes
Understand intermittent failures

Example Scenarios

Why is this function failing?

Use gitnexus_context to see all callers and callees, then check for external dependencies or data flow issues.

Trace where this error comes from

Use gitnexus_query with the error message text to find throw sites, then trace backwards through the call chain.

Who calls this method?

Use gitnexus_context to get all incoming calls categorized by relationship type (CALLS, IMPORTS).

This endpoint returns 500

Query for the endpoint handler, use context to trace callees, look for external API calls or missing error handling.

Workflow

Follow these steps for effective debugging:

Step-by-Step Guide

1. Understand the Symptom Before querying the graph, clearly identify:

Error message (exact text)
Unexpected behavior description
Which endpoint/function exhibits the issue
When it happens (always? intermittent? specific conditions?)

2. Query for Related Code

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

Returns:

Processes involving this error (e.g., CheckoutFlow, ErrorHandling)
Symbols related to the error (validatePayment, handlePaymentError, PaymentException)
Prioritized by relevance

3. Get Full Context on Suspect

gitnexus_context({name: "validatePayment"})

Returns:

Incoming calls: Who triggers this function
Outgoing calls: What this function depends on
Processes: Execution flows involving this symbol

Pay special attention to outgoing calls marked as external APIs—these are common failure points.

4. Trace Execution Flow

READ gitnexus://repo/{name}/process/CheckoutFlow

See exactly where the suspect function appears in the execution chain. 5. Custom Call Chain Traces (Advanced) If you need deeper analysis:

MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain

This finds all paths leading to the suspect function. 6. Confirm Root Cause Read the source files to verify your hypothesis.

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

GitNexus provides different approaches depending on the symptom:

Symptom	GitNexus Approach	Tools to Use
Error message	Find throw sites, trace backwards	`query` for error text → `context` on throw sites
Wrong return value	Trace data flow through callees	`context` on the function → examine outgoing calls
Intermittent failure	Look for external dependencies	`context` → find async calls, external APIs
Performance issue	Find hot paths (many callers)	`context` → check incoming calls count
Recent regression	Map what your changes affect	`detect_changes` to see affected processes

Tools for Debugging

gitnexus_query

Find code related to an error:

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

Returns:

{
  processes: [
    {
      summary: "CheckoutFlow",
      symbols: ["validatePayment", "handlePaymentError"]
    },
    {
      summary: "ErrorHandling",
      symbols: ["PaymentException", "logError"]
    }
  ]
}

Best for:

Finding code related to error messages
Discovering error handling flows
Locating exception definitions

gitnexus_context

Get full context on a suspect:

gitnexus_context({name: "validatePayment"})

Returns:

{
  symbol: {
    uid: "Function:validatePayment",
    filePath: "src/payments/validator.ts",
    startLine: 42
  },
  incoming: {
    calls: ["processCheckout", "webhookHandler"]
  },
  outgoing: {
    calls: [
      "verifyCard",
      "fetchRates"  // ⚠️ External API call!
    ]
  },
  processes: [
    {
      name: "CheckoutFlow",
      step_index: 3,
      total_steps: 7
    }
  ]
}

Best for:

Finding who calls the failing function
Discovering external dependencies
Understanding data flow

gitnexus_cypher

Custom call chain traces:

// Find all paths to validatePayment (up to 2 hops)
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain

Returns:

chains:
  - ["checkoutHandler", "processCheckout", "validatePayment"]
  - ["webhookHandler", "validatePayment"]
  - ["apiMiddleware", "processCheckout", "validatePayment"]

Best for:

Complex call chain analysis
Finding all paths to a function
Debugging indirect dependencies

Always read gitnexus://repo/{name}/schema before writing Cypher queries to understand the graph structure.

Example: “Payment endpoint returns 500 intermittently”

Here’s a complete debugging walkthrough:

Step 1: Understand the Symptom

What: /api/checkout endpoint returns 500
When: Intermittent (not every request)
Error: “Payment validation failed”

Step 2: Query for Error Handling

gitnexus_query({query: "payment error handling"})

Result:

Processes:
  1. CheckoutFlow (7 symbols)
  2. ErrorHandling (4 symbols)

Symbols:
  - validatePayment (src/payments/validator.ts:42)
  - handlePaymentError (src/errors/payment.ts:15)

Step 3: Get Context on validatePayment

gitnexus_context({name: "validatePayment"})

Result:

Incoming calls:
  - processCheckout
  - webhookHandler

Outgoing calls:
  - verifyCard
  - fetchRates ← External API! ⚠️

Processes:
  - CheckoutFlow (step 3/7)

Hypothesis: fetchRates is an external API call—might be timing out!

Step 4: Trace Execution Flow

READ gitnexus://repo/my-app/process/CheckoutFlow

Result:

CheckoutFlow:
  1. validateCart
  2. processCheckout
  3. validatePayment
     ↓ calls verifyCard
     ↓ calls fetchRates ← External API
  4. chargeCustomer
  5. saveTransaction

Step 5: Read Source Code

Read src/payments/validator.ts:42:

async function validatePayment(amount: number) {
  const rates = await fetchRates();  // ⚠️ No timeout!
  // ...
}

Root cause confirmed: fetchRates calls an external API without a proper timeout. When the API is slow, the request hangs and eventually times out with 500. Fix: Add timeout to external API call.

Advanced Debugging Techniques

Finding All Error Throw Sites

MATCH (f:Function)-[:CodeRelation {type: 'CALLS'}]->(err)
WHERE err.name CONTAINS 'Error' OR err.name CONTAINS 'Exception'
RETURN f.name, f.filePath, err.name
ORDER BY f.filePath

Tracing Data Flow

Use context to find where data is created (incoming refs)
Follow outgoing calls to see transformations
Check process trace to see the full pipeline

Debugging Async Issues

context to find all async function calls
Look for missing await or error handling
Check for race conditions (multiple callers of same async function)

Best Practices

Look for External Calls

External APIs are common failure points—check context outgoing calls.

Trace Backwards

Start at the error, use context to find callers, repeat until you reach the entry point.

Check Processes

Process traces show the full execution chain—useful for understanding flow.

Use Cypher for Complex Traces

For multi-hop call chains, write custom Cypher queries.

Common Pitfalls

Missing Error Handling

gitnexus_context({name: "apiCall"})

If outgoing calls include external APIs but incoming calls don’t show try/catch wrappers, there might be missing error handling.

Circular Dependencies

MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*2..4]->(a)
WHERE a.name = "myFunction"
RETURN path

This finds circular call chains that might cause stack overflows.

Hot Paths

gitnexus_context({name: "expensiveFunction"})

If incoming calls show many callers, this might be a performance bottleneck.

Next Steps

Learn Impact Analysis

Once you’ve fixed the bug, use impact analysis to ensure your changes don’t break other code

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

Debugging with GitNexus

When to Use This Skill

Example Scenarios

Workflow

Step-by-Step Guide

Checklist

Debugging Patterns

Tools for Debugging

gitnexus_query

gitnexus_context

gitnexus_cypher

Example: “Payment endpoint returns 500 intermittently”

Step 1: Understand the Symptom

Step 2: Query for Error Handling

Step 3: Get Context on validatePayment

Step 4: Trace Execution Flow

Step 5: Read Source Code

Advanced Debugging Techniques

Finding All Error Throw Sites

Tracing Data Flow

Debugging Async Issues

Best Practices

Look for External Calls

Trace Backwards

Check Processes

Use Cypher for Complex Traces

Common Pitfalls

Missing Error Handling

Circular Dependencies

Hot Paths

Next Steps

Learn Impact Analysis

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

​When to Use This Skill

​Example Scenarios

​Workflow

​Step-by-Step Guide

​Checklist

​Debugging Patterns

​Tools for Debugging

​gitnexus_query

​gitnexus_context

​gitnexus_cypher

​Example: “Payment endpoint returns 500 intermittently”

​Step 1: Understand the Symptom

​Step 2: Query for Error Handling

​Step 3: Get Context on validatePayment

​Step 4: Trace Execution Flow

​Step 5: Read Source Code

​Advanced Debugging Techniques

​Finding All Error Throw Sites

​Tracing Data Flow

​Debugging Async Issues

​Best Practices

Look for External Calls

Trace Backwards

Check Processes

Use Cypher for Complex Traces

​Common Pitfalls

​Missing Error Handling

​Circular Dependencies

​Hot Paths

​Next Steps

Learn Impact Analysis

Build docs developers (and LLMs) love

When to Use This Skill

Example Scenarios

Workflow

Step-by-Step Guide

Checklist

Debugging Patterns

Tools for Debugging

gitnexus_query

gitnexus_context

gitnexus_cypher

Example: “Payment endpoint returns 500 intermittently”

Step 1: Understand the Symptom

Step 2: Query for Error Handling

Step 3: Get Context on validatePayment

Step 4: Trace Execution Flow

Step 5: Read Source Code

Advanced Debugging Techniques

Finding All Error Throw Sites

Tracing Data Flow

Debugging Async Issues

Best Practices

Common Pitfalls

Missing Error Handling

Circular Dependencies

Hot Paths

Next Steps