frappe-agent-debugger

# 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 violation | Linked document missing |
| `OperationalError: 1213` | Deadlock | Reduce transaction scope |
| `InternalError: 1366` | Invalid character for charset | Check input encoding |

### Permission Errors

| Error Pattern | Likely Cause | Fix |
|---------------|-------------|-----|
| `frappe.PermissionError` | User lacks role permission | Check Role Permission Manager |
| 403 on API call | Missing `frappe.has_permission()` or wrong `@frappe.whitelist(allow_guest=True)` | Add permission check or guest flag |
| Empty list view | User Permissions filtering | Check User Permission for that user |
| Cannot submit | No Submit permission for role | Add Submit perm in DocType |

## Debug Tools

### bench console (Python REPL)
```bash
bench --site {site} console
# Then:
frappe.get_doc("Sales Invoice", "SINV-00001")  # Inspect document
frappe.db.sql("SELECT name FROM `tabSales Invoice` LIMIT 5")  # Raw SQL
frap