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 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)

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
frappe.get_hooks("doc_events")  # Inspect active hooks
frappe.get_all("Server Script", filters={"disabled": 0}, fields=["name", "script_type"])

bench mariadb (SQL shell)

bench --site {site} mariadb
-- Then:
SHOW CREATE TABLE `tabSales Invoice`;
SELECT * FROM `tabError Log` ORDER BY creation DESC LIMIT 10;

bench doctor

bench doctor  # Check scheduler, workers, background jobs

frappe.logger()

logger = frappe.logger("my_debug", allow_site=True)
logger.info(f"Variable value: {my_var}")
# Logs to: sites/{site}/logs/my_debug.log

Browser DevTools

Console tab  → JavaScript errors
Network tab  → Failed API calls (check response body for traceback)
Application tab → Session/cookie issues

Log File Locations

Log	Path	Contains
Frappe web	sites/{site}/logs/frappe.log	Web request errors
Worker	sites/{site}/logs/worker.log	Background job errors
Scheduler	sites/{site}/logs/scheduler.log	Scheduled task output
Custom logger	sites/{site}/logs/{name}.log	frappe.logger("{name}") output
Bench	~/.bench/logs/bench.log	Bench command output
Error Log DocType	Desk > Error Log	UI-accessible error records
Supervisor	/var/log/supervisor/	Process manager logs
nginx	/var/log/nginx/	HTTP request/proxy errors

Common Error Patterns Table

Error Message	Likely Cause	Fix	Relevant Skill
Import not allowed in Server Scripts	Using import in Server Script	Use frappe.utils.* or move to Controller	frappe-errors-serverscripts
Cannot read properties of undefined	JS accessing field before form load	Add frm.doc.field null check	frappe-errors-clientscripts
DocType X not found	Missing app install or migration	bench migrate or bench install-app	frappe-ops-bench
Scheduler is not running	Workers stopped	bench doctor, restart workers	frappe-ops-bench
BrokenPipeError	gunicorn timeout on long operation	Use frappe.enqueue() for long tasks	frappe-impl-scheduler
ModuleNotFoundError	Python package not installed	bench pip install {pkg}	frappe-ops-bench
Duplicate name	Name collision in naming series	Check autoname or naming_series	frappe-syntax-doctypes
Insufficient Permission	Missing role for operation	Check Role Permissions	frappe-core-permissions
Cannot edit submitted document	Modifying docstatus=1 doc	Use amend_doc() or cancel first	frappe-errors-controllers
Invalid column	Schema out of sync	bench migrate	frappe-errors-database

Agent Output Format

ALWAYS produce debugging output in this format:

## Debug Report

### Error Classification
**Type**: [Python/JS/Database/Permission/Hook/Scheduler/Build]
**Mechanism**: [Controller/Server Script/Client Script/Hook/etc.]

### Root Cause
[One-sentence diagnosis]

### Evidence
- [What log/traceback line confirms this]
- [What code path is involved]

### Fix
[Corrected code or configuration change]

### Verification Steps
1. [How to confirm the fix works]
2. [What to check in logs/UI]

### Referenced Skills
- `frappe-*`: [what was consulted]

Debugging Decision Tree

ERROR RECEIVED
|
+-- Has traceback?
|   +-- YES: Read LAST line first (actual error)
|   |   +-- Contains ".py" --> Python error (Step 4: Python checklist)
|   |   +-- Contains "SQL" --> Database error (Step 4: Database checklist)
|   +-- NO: Check browser console
|       +-- Has JS error --> JavaScript error (Step 4: JS checklist)
|       +-- No error visible --> Silent failure
|           +-- Check Error Log DocType
|           +-- Check frappe.log
|           +-- Add frappe.logger() statements
|
+-- Error after bench command?
|   +-- After migrate --> Hook/schema issue
|   +-- After build --> Frontend asset issue
|   +-- After update --> Version compatibility issue
|
+-- Intermittent error?
    +-- Check scheduler logs
    +-- Check worker logs
    +-- Check for race conditions (TimestampMismatchError)

See references/checklists.md for complete diagnosis checklists. See references/examples.md for debugging walkthrough examples. See references/advanced-debugging.md for VS Code DAP setup, bench console patterns, mariadb diagnostics, and profiling tools.