Debugging

Investigate bugs by tracing execution paths and understanding code relationships.

Quick Start

"Why is the login failing with 'Invalid token'?"

"Find code that throws AuthenticationError"

"What calls validateToken?"

"What changed recently in the auth module?"

When to Use

Use this workflow when:

Investigating error messages
Tracing unexpected behavior
Finding root causes
Identifying regression sources

Debugging Patterns

Symptom	Approach
Error message	Search for error text, trace throw sites
Wrong return value	Trace data flow through callees
Intermittent failure	Look for external calls, race conditions
Recent regression	Use detect_impact for recent changes
Performance issue	Trace execution flow, find hot paths

Debugging Workflow

Start with the error message or behavior:

"Find code related to 'Invalid token' error"

Uses: noodlbox_query_with_context tool

Look for:

Where the error is thrown
What conditions trigger it
Related validation logic

Identify the Suspect Function

Narrow down to the specific function:

"Find the validateToken function"

Review the code to understand its logic.

Trace Callers (Entry Points)

Find how the suspect code is reached:

"What calls validateToken?"

Uses: noodlbox_raw_cypher_query tool

MATCH (caller)-[:CALLS]->(target:Symbol {name: "validateToken"})
RETURN caller.name, caller.file_path
ORDER BY caller.file_path

This shows all paths that lead to the error.

Trace Callees (Dependencies)

Find what the suspect code depends on:

"What does validateToken call?"

MATCH (source:Symbol {name: "validateToken"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path, callee.kind

This reveals:

External service calls
Database queries
Other potential failure points

Check Recent Changes

If this is a regression, find what changed:

"What changed recently that might affect authentication?"

Uses: noodlbox_detect_impact tool

Review changed_symbols and potentially_affected for recent modifications.

Trace the Full Execution Flow

For complex bugs, trace the entire process:

"Trace the authentication process"

Uses: map://current/process/{id} resource

See the exact function call sequence from start to finish.

Debugging Checklist

Search for error message or related code
Identify the specific function where the error occurs
Trace all callers to understand entry points
Trace all callees to find dependencies
Check for recent changes with detect_impact
Review the full execution flow if needed
Form hypothesis and verify

Example: Debug Intermittent 500 Error

Symptom: Users occasionally get 500 errors on the checkout page

Find the Error Source

"Find code that handles checkout errors"

Locate the checkout controller and error handling.

Identify External Calls

MATCH (method)-[:DEFINED_IN]->(class:Symbol {name: "CheckoutController"})
MATCH (method)-[:CALLS]->(external)
WHERE external.file_path CONTAINS "service" OR external.file_path CONTAINS "client"
RETURN method.name, external.name, external.file_path

Result: processPayment calls PaymentGateway.charge

Trace the Payment Flow

"Trace the processPayment process"

See all functions involved in payment processing.

Check for Race Conditions

MATCH (method)-[:CALLS]->(dep)
WHERE method.name = "processPayment"
AND (dep.name CONTAINS "async" OR dep.name CONTAINS "Promise" OR dep.name CONTAINS "await")
RETURN dep.name, dep.file_path

Look for concurrent operations that might conflict.

Review Recent Changes

"What changed recently in the payment module?"

Finding: A recent change modified the timeout handling in PaymentGateway.

Useful Cypher Patterns for Debugging

Find Error Throw Sites

MATCH (sym:Symbol)
WHERE sym.body CONTAINS "throw" AND sym.body CONTAINS "Error"
RETURN sym.name, sym.file_path
LIMIT 20

Find Functions with External Calls

MATCH (func:Symbol {kind: "function"})-[:CALLS]->(dep)
WHERE dep.file_path CONTAINS "node_modules"
   OR dep.name CONTAINS "fetch"
   OR dep.name CONTAINS "http"
RETURN func.name, func.file_path, collect(dep.name) as external_deps

Find Functions in a Call Chain

MATCH path = (entry:Symbol {name: "handleRequest"})-[:CALLS*1..5]->(target)
WHERE target.name = "validateToken"
RETURN [n IN nodes(path) | n.name] as call_chain

Tools Reference

Purpose	Tool
Find related code	`noodlbox_query_with_context`
Trace relationships	`noodlbox_raw_cypher_query`
Check recent changes	`noodlbox_detect_impact`
Full execution flow	`map://current/process/{id}`

On this page