/frappe-agent-debugger

name: frappe-agent-debugger
description: >
  Use when debugging Frappe errors, using bench console for live inspection, analyzing tracebacks, or reading Frappe log files.
  Prevents wasted debugging time from ignoring log context, misreading tracebacks, and not using bench console effectively.
  Covers bench console, frappe.logger, error log DocType, traceback analysis, common error patterns, log file locations, pdb/debugger integration, VS Code DAP, profiling, Frappe Recorder, mariadb diagnostics.
  Keywords: debug, bench console, traceback, error log, frappe.logger, pdb, debugging, log analysis, inspect, VS Code, DAP, profiling, recorder, mariadb, monitor, ERPNext error, how to debug, find the bug, what went wrong, stack trace, error message..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Frappe Debugging Agent

Systematically diagnoses Frappe/ERPNext issues by classifying errors, locating relevant code, and applying targeted diagnosis checklists.

**Purpose**: Eliminate trial-and-error debugging — follow a deterministic diagnostic workflow.

When to Use This Agent

ERROR ANALYSIS TRIGGER
|
+-- Python traceback or error message
|   "ImportError: cannot import name X from frappe"
|   --> USE THIS AGENT
|
+-- JavaScript console error
|   "Uncaught TypeError: frm.set_value is not a function"
|   --> USE THIS AGENT
|
+-- Silent failure (no error, wrong behavior)
|   "Server Script runs but nothing happens"
|   --> USE THIS AGENT
|
+-- Scheduler/background job failure
|   "Job X failed" in scheduler logs
|   --> USE THIS AGENT
|
+-- Build/asset errors
|   "Module not found" or blank page after build
|   --> USE THIS AGENT

Debugging Workflow

STEP 1: CLASSIFY ERROR TYPE
  Python | JavaScript | Database | Permission | Hook | Scheduler | Build

STEP 2: IDENTIFY THE MECHANISM
  Controller | Server Script | Client Script | Hook | Scheduler | API

STEP 3: LOCATE RELEVANT CODE
  Use Frappe file path conventions to find source

STEP 4: APPLY DIAGNOSIS CHECKLIST
  Run type-specific checklist for the error class

STEP 5: SUGGEST FIX
  Provide corrected code + reference relevant frappe-* skills

See [references/workflow.md](references/workflow.md) for detailed steps.

Step 1: Error Classification

| Error Type | Indicators | Primary Tool | |------------|-----------|--------------| | **Python** | Traceback with `.py` files | `bench console`, logs | | **JavaScript** | Browser console error, `cur_frm` issues | Browser DevTools | | **Database** | `OperationalError`, `IntegrityError` | `bench mariadb` | | **Permission** | `frappe.PermissionError`, 403 responses | Permission Inspector | | **Hook** | Errors after `bench migrate`, wrong events | `bench doctor` | | **Scheduler** | `bench doctor` warnings, RQ failures | Scheduler logs | | **Build** | Missing assets, blank page, module errors | `bench build --verbose` |

Step 2: Mechanism Identification

| Symptom | Likely Mechanism | |---------|-----------------| | Error during form save/submit | Controller or Server Script (validate/on_submit) | | Error on page load | Client Script or Web Template | | Error message from API call | Whitelisted method or REST API handler | | Error in background | Scheduler event or `frappe.enqueue()` job | | Error after `bench migrate` | Hook configuration or patch | | Error after `bench build` | Frontend asset pipeline |

Step 3: File Path Conventions

ALWAYS check these locations based on the mechanism:

| Mechanism | File Path Pattern | |-----------|-------------------| | Controller | `apps/{app}/{app}/{module}/{doctype}/{doctype}.py` | | Server Script | Desk > Server Script list (stored in DB) | | Client Script | Desk > Client Script list (stored in DB) | | hooks.py | `apps/{app}/{app}/hooks.py` | | Scheduler | `apps/{app}/{app}/tasks.py` or hooks.py `scheduler_events` | | Whitelisted | `apps/{app}/{app}/{module}/*.py` (search for `@frappe.whitelist`) | | Jinja | `apps/{app}/{app}/templates/` | | Patches | `apps/{app}/{app}/patches/` |

Step 4: Diagnosis Checklists (Quick Reference)

Python Errors

| Error Pattern | Likely Cause | Fix | |---------------|-------------|-----| | `AttributeError: 'NoneType'` | `frappe.get_doc()` returned None | Check document exists first | | `ValidationError` | `frappe.throw()` in validate | Read the message — it IS the diagnosis | | `ImportError` | Wrong import path or Server Script using imports | Server Scripts CANNOT import | | `LinkValidationError` | Referenced document does not exist | Verify Link field target exists | | `TimestampMismatchError` | Concurrent edit conflict | Reload document before save | | `DuplicateEntryException` | Unique constraint violation | Check naming series or unique fields | | `MandatoryError` | Required field is empty | Set field before save/submit | | `InvalidStatusError` | Wrong docstatus transition | Follow 0→1→2 sequence | | `CircularLinkingError` | Self-referencing parent-child | Fix document hierarchy |

JavaScript Errors

| Error Pattern | Likely Cause | Fix | |---------------|-------------|-----| | `frm.X is not a function` | Wrong API or stale code | Clear cache, check API name | | `cur_frm is undefined` | Code runs outside form context | Use `frm` from handler parameter | | `Uncaught Promise` | Missing async/await on `frappe.call` | Add callback or await | | `field undefined` in `frm.doc` | Field does not exist on DocType | Check fieldname spelling | | Form not refreshing | Missing `frm.refresh_fields()` | Add refresh after `set_value` |

Database Errors

| Error Pattern | Likely Cause | Fix | |---------------|-------------|-----| | `OperationalError: 1054` | Column does not exist | Run `bench migrate` | | `OperationalError: 1146` | Table does not exist | Run `bench migrate` | | `IntegrityError: 1062` | Duplicate primary key | Check naming/autoname | | `IntegrityError: 1452` | Foreign key violati