Skip to content

Debug an Issue

In this tutorial, you'll use the Debug agent to trace a reported issue to its origin in the knowledge graph and get a fix at the source — not a symptom patch.

Prerequisites

  • Potpie CLI installed and set up (Quickstart)
  • A repository registered and parsed to ready status

Steps

1. Pull debugging context

Ask Potpie to resolve the context an agent should read before investigating, scoped to the failing area:

potpie resolve "debug 500 on password reset" --intent debugging

Relevant context for: password reset failure

Service:   auth-api
Entry:     POST /api/auth/reset-password  (app/routes/auth.py:88)
Flow:      reset_password() → UserRepo.get_by_email() (app/repo/user.py:40)
Prior:     fix #312 "guard against missing email on reset" (reverted)

2. Describe the issue to the Debug agent

Paste an error message, stack trace, or describe the unexpected behavior. Include any context about when it occurs.

> "Users are getting a 500 error when trying to reset their password.
>  The error log shows: NoneType has no attribute 'email'"

Tip

Follow-up messages within the same session retain full context. Start with a high-level symptom and narrow to the root cause across subsequent turns.

3. Let Debug investigate

The Debug agent applies its eight-step methodology automatically:

  1. Understand and validate — confirms the reported behavior against the codebase
  2. Explore and hypothesize — traverses relevant code paths in the knowledge graph
  3. Identify root cause — pins the failure to a specific file and line
  4. Generalize — checks if the same pattern appears elsewhere
  5. Design solution — generates a targeted fix scoped to the root cause
  6. Scrutinize — evaluates against edge cases and traces side effects
  7. Implement — produces corrected code with exact file paths
  8. Verify — validates the fix against the original failure

3. Review the result

Debug returns:

  • The root cause traced to its true origin
  • A mapped path from origin to symptom
  • A fix that resolves the underlying issue (not just the reported instance)
Root cause: UserRepo.get_by_email() (app/repo/user.py:40) returns None for
unknown emails, but reset_password() (app/routes/auth.py:94) accesses
user.email without a null check.

Path to symptom: reset-password route → get_by_email() → None → AttributeError → 500

Fix (app/routes/auth.py:94):
    user = UserRepo.get_by_email(email)
+   if user is None:
+       return JSONResponse(status_code=404, detail="User not found")
    send_reset_link(user.email)

This is a source fix — every caller of get_by_email() that assumes a non-None
result is now protected at the route boundary.

4. Record the learning (optional)

Capture the fix as durable project memory so future agents don't rediscover it:

potpie record --type fix \
  --summary "Null-guard get_by_email() callers; reset-password returned 500 on unknown email"

Key principles

Warning

User-reported symptoms and suggested fixes are treated as starting points for investigation, not conclusions. The real issue is often upstream of where the problem surfaces.

  • A fix at the source prevents the problem for every downstream caller
  • A fix at the symptom only handles one path
  • Debug always identifies which type of fix it's applying and why

Example scenarios

Scenario What Debug traces
Null pointer exception Through service and data layers to the missing initialization
Memory leak Through object lifecycle and dependency chains to the source
Race condition Through concurrent access paths to the unprotected shared state
Auth bypass Through middleware chain to the misconfigured route

Next steps