frappe-agent-debugger

Name: frappe-agent-debugger
Author: Impertio-Studio

151stars49forks

How to install frappe-agent-debugger?

impertio-studio/frappe_claude_skill_package/frappe-agent-debugger

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-agent-debugger

Installs into the current project.

Summary

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.log

Files · 1

View on GitHub

SKILL.md

1	# Frappe Debugging Agent
2
3	Systematically diagnoses Frappe/ERPNext issues by classifying errors, locating relevant code, and applying targeted diagnosis checklists.
4
5	Purpose: Eliminate trial-and-error debugging — follow a deterministic diagnostic workflow.
6
7	## When to Use This Agent
8
9	```
10	ERROR ANALYSIS TRIGGER
11	\|
12	+-- Python traceback or error message
13	\| "ImportError: cannot import name X from frappe"
14	\| --> USE THIS AGENT
15	\|
16	+-- JavaScript console error
17	\| "Uncaught TypeError: frm.set_value is not a function"
18	\| --> USE THIS AGENT
19	\|
20	+-- Silent failure (no error, wrong behavior)
21	\| "Server Script runs but nothing happens"
22	\| --> USE THIS AGENT
23	\|
24	+-- Scheduler/background job failure
25	\| "Job X failed" in scheduler logs
26	\| --> USE THIS AGENT
27	\|
28	+-- Build/asset errors
29	\| "Module not found" or blank page after build
30	\| --> USE THIS AGENT
31	```
32
33	## Debugging Workflow
34
35	```
36	STEP 1: CLASSIFY ERROR TYPE
37	Python \| JavaScript \| Database \| Permission \| Hook \| Scheduler \| Build
38
39	STEP 2: IDENTIFY THE MECHANISM
40	Controller \| Server Script \| Client Script \| Hook \| Scheduler \| API
41
42	STEP 3: LOCATE RELEVANT CODE
43	Use Frappe file path conventions to find source
44
45	STEP 4: APPLY DIAGNOSIS CHECKLIST
46	Run type-specific checklist for the error class
47
48	STEP 5: SUGGEST FIX
49	Provide corrected code + reference relevant frappe-* skills
50	```
51
52	See [references/workflow.md](references/workflow.md) for detailed steps.
53
54	## Step 1: Error Classification
55
56	\| Error Type \| Indicators \| Primary Tool \|
57	\|------------\|-----------\|--------------\|
58	\| Python \| Traceback with `.py` files \| `bench console`, logs \|
59	\| JavaScript \| Browser console error, `cur_frm` issues \| Browser DevTools \|
60	\| Database \| `OperationalError`, `IntegrityError` \| `bench mariadb` \|
61	\| Permission \| `frappe.PermissionError`, 403 responses \| Permission Inspector \|
62	\| Hook \| Errors after `bench migrate`, wrong events \| `bench doctor` \|
63	\| Scheduler \| `bench doctor` warnings, RQ failures \| Scheduler logs \|
64	\| Build \| Missing assets, blank page, module errors \| `bench build --verbose` \|
65
66	## Step 2: Mechanism Identification
67
68	\| Symptom \| Likely Mechanism \|
69	\|---------\|-----------------\|
70	\| Error during form save/submit \| Controller or Server Script (validate/on_submit) \|
71	\| Error on page load \| Client Script or Web Template \|
72	\| Error message from API call \| Whitelisted method or REST API handler \|
73	\| Error in background \| Scheduler event or `frappe.enqueue()` job \|
74	\| Error after `bench migrate` \| Hook configuration or patch \|
75	\| Error after `bench build` \| Frontend asset pipeline \|
76
77	## Step 3: File Path Conventions
78
79	ALWAYS check these locations based on the mechanism:
80
81	\| Mechanism \| File Path Pattern \|
82	\|-----------\|-------------------\|
83	\| Controller \| `apps/{app}/{app}/{module}/{doctype}/{doctype}.py` \|
84	\| Server Script \| Desk > Server Script list (stored in DB) \|
85	\| Client Script \| Desk > Client Script list (stored in DB) \|
86	\| hooks.py \| `apps/{app}/{app}/hooks.py` \|
87	\| Scheduler \| `apps/{app}/{app}/tasks.py` or hooks.py `scheduler_events` \|
88	\| Whitelisted \| `apps/{app}/{app}/{module}/*.py` (search for `@frappe.whitelist`) \|
89	\| Jinja \| `apps/{app}/{app}/templates/` \|
90	\| Patches \| `apps/{app}/{app}/patches/` \|
91
92	## Step 4: Diagnosis Checklists (Quick Reference)
93
94	### Python Errors
95
96	\| Error Pattern \| Likely Cause \| Fix \|
97	\|---------------\|-------------\|-----\|
98	\| `AttributeError: 'NoneType'` \| `frappe.get_doc()` returned None \| Check document exists first \|
99	\| `ValidationError` \| `frappe.throw()` in validate \| Read the message — it IS the diagnosis \|
100	\| `ImportError` \| Wrong import path or Server Script using imports \| Server Scripts CANNOT import \|
101	\| `LinkValidationError` \| Referenced document does not exist \| Verify Link field target exists \|
102	\| `TimestampMismatchError` \| Concurrent edit conflict \| Reload document before save \|
103	\| `DuplicateEntryException` \| Unique constraint violation \| Check naming series or unique fields \|
104	\| `MandatoryError` \| Required field is empty \| Set field before save/submit \|
105	\| `InvalidStatusError` \| Wrong docstatus transition \| Follow 0→1→2 sequence \|
106	\| `Cir

People who liked this also viewed

6 picks

Type

frappe-agent-debugger

151stars49forks

View on GitHub

How to install frappe-agent-debugger?

impertio-studio/frappe_claude_skill_package/frappe-agent-debugger

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-agent-debugger

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Frappe Debugging Agent
2
3	Systematically diagnoses Frappe/ERPNext issues by classifying errors, locating relevant code, and applying targeted diagnosis checklists.
4
5	Purpose: Eliminate trial-and-error debugging — follow a deterministic diagnostic workflow.
6
7	## When to Use This Agent
8
9	```
10	ERROR ANALYSIS TRIGGER
11	\|
12	+-- Python traceback or error message
13	\| "ImportError: cannot import name X from frappe"
14	\| --> USE THIS AGENT
15	\|
16	+-- JavaScript console error
17	\| "Uncaught TypeError: frm.set_value is not a function"
18	\| --> USE THIS AGENT
19	\|
20	+-- Silent failure (no error, wrong behavior)
21	\| "Server Script runs but nothing happens"
22	\| --> USE THIS AGENT
23	\|
24	+-- Scheduler/background job failure
25	\| "Job X failed" in scheduler logs
26	\| --> USE THIS AGENT
27	\|
28	+-- Build/asset errors
29	\| "Module not found" or blank page after build
30	\| --> USE THIS AGENT
31	```
32
33	## Debugging Workflow
34
35	```
36	STEP 1: CLASSIFY ERROR TYPE
37	Python \| JavaScript \| Database \| Permission \| Hook \| Scheduler \| Build
38
39	STEP 2: IDENTIFY THE MECHANISM
40	Controller \| Server Script \| Client Script \| Hook \| Scheduler \| API
41
42	STEP 3: LOCATE RELEVANT CODE
43	Use Frappe file path conventions to find source
44
45	STEP 4: APPLY DIAGNOSIS CHECKLIST
46	Run type-specific checklist for the error class
47
48	STEP 5: SUGGEST FIX
49	Provide corrected code + reference relevant frappe-* skills
50	```
51
52	See [references/workflow.md](references/workflow.md) for detailed steps.
53
54	## Step 1: Error Classification
55
56	\| Error Type \| Indicators \| Primary Tool \|
57	\|------------\|-----------\|--------------\|
58	\| Python \| Traceback with `.py` files \| `bench console`, logs \|
59	\| JavaScript \| Browser console error, `cur_frm` issues \| Browser DevTools \|
60	\| Database \| `OperationalError`, `IntegrityError` \| `bench mariadb` \|
61	\| Permission \| `frappe.PermissionError`, 403 responses \| Permission Inspector \|
62	\| Hook \| Errors after `bench migrate`, wrong events \| `bench doctor` \|
63	\| Scheduler \| `bench doctor` warnings, RQ failures \| Scheduler logs \|
64	\| Build \| Missing assets, blank page, module errors \| `bench build --verbose` \|
65
66	## Step 2: Mechanism Identification
67
68	\| Symptom \| Likely Mechanism \|
69	\|---------\|-----------------\|
70	\| Error during form save/submit \| Controller or Server Script (validate/on_submit) \|
71	\| Error on page load \| Client Script or Web Template \|
72	\| Error message from API call \| Whitelisted method or REST API handler \|
73	\| Error in background \| Scheduler event or `frappe.enqueue()` job \|
74	\| Error after `bench migrate` \| Hook configuration or patch \|
75	\| Error after `bench build` \| Frontend asset pipeline \|
76
77	## Step 3: File Path Conventions
78
79	ALWAYS check these locations based on the mechanism:
80
81	\| Mechanism \| File Path Pattern \|
82	\|-----------\|-------------------\|
83	\| Controller \| `apps/{app}/{app}/{module}/{doctype}/{doctype}.py` \|
84	\| Server Script \| Desk > Server Script list (stored in DB) \|
85	\| Client Script \| Desk > Client Script list (stored in DB) \|
86	\| hooks.py \| `apps/{app}/{app}/hooks.py` \|
87	\| Scheduler \| `apps/{app}/{app}/tasks.py` or hooks.py `scheduler_events` \|
88	\| Whitelisted \| `apps/{app}/{app}/{module}/*.py` (search for `@frappe.whitelist`) \|
89	\| Jinja \| `apps/{app}/{app}/templates/` \|
90	\| Patches \| `apps/{app}/{app}/patches/` \|
91
92	## Step 4: Diagnosis Checklists (Quick Reference)
93
94	### Python Errors
95
96	\| Error Pattern \| Likely Cause \| Fix \|
97	\|---------------\|-------------\|-----\|
98	\| `AttributeError: 'NoneType'` \| `frappe.get_doc()` returned None \| Check document exists first \|
99	\| `ValidationError` \| `frappe.throw()` in validate \| Read the message — it IS the diagnosis \|
100	\| `ImportError` \| Wrong import path or Server Script using imports \| Server Scripts CANNOT import \|
101	\| `LinkValidationError` \| Referenced document does not exist \| Verify Link field target exists \|
102	\| `TimestampMismatchError` \| Concurrent edit conflict \| Reload document before save \|
103	\| `DuplicateEntryException` \| Unique constraint violation \| Check naming series or unique fields \|
104	\| `MandatoryError` \| Required field is empty \| Set field before save/submit \|
105	\| `InvalidStatusError` \| Wrong docstatus transition \| Follow 0→1→2 sequence \|
106	\| `Cir

People who liked this also viewed

6 picks

Type