frappe-errors-controllers

Diagnose Frappe Document Controller hook errors across lifecycle phases.

163|53|Updated Jan 14, 2026
One-click install
npx skills add https://github.com/Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-errors-controllers-impertio-studio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: frappe-errors-controllers
Source: https://github.com/Impertio-Studio/Frappe_Claude_Skill_Package/tree/main/skills/source/errors/frappe-errors-controllers
Command: npx skills add https://github.com/Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-errors-controllers-impertio-studio

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you diagnose and resolve production-breaking errors caused by incorrect Document Controller hook usage in Frappe, including naming failures, validation loops, missing lifecycle logic, permission/query issues, and NestedSet or controller class override conflicts.

Core Features & Use Cases

  • Lifecycle-phase error diagnosis: Map a failing controller behavior to the correct hook phase (naming, validation/save, submit/cancel, and permission/get_list) and identify the most likely root cause.
  • Production-safe fixes for common controller mistakes: Prevent autoname failures, avoid recursion from self.save() in hooks, ensure submit validation happens in before_submit, use db_set for on_update changes, and guarantee super() is called in overrides.
  • Guardrails for advanced edge cases: Handle extend_doctype_class conflicts (v16+), permission_query_conditions SQL errors and injection risks, NestedSet circular references, and recursion via flags for cross-document updates.

Quick Start

Use the frappe-errors-controllers skill to analyze why a specific controller hook is failing and request a corrected hook implementation and naming/permission fix for your Frappe version (v14, v15, or v16).

Frequently Asked Questions about frappe-errors-controllers

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Frappe controller hook cause infinite recursion during on_update?

Infinite recursion in Frappe controller hooks usually happens when calling self.save() inside on_update. Use db_set for field updates and apply recursion guards via document flags to prevent the loop.

How do I debug Frappe autoname failures in document controllers?

Debug Frappe autoname failures by mapping the naming hook phase to identify root causes like incorrect patterns or missing logic. Apply production-safe hook patterns to resolve the naming sequence.

Where should validation logic go for Frappe document submission?

Validation logic for Frappe document submission belongs in the before_submit hook phase. Placing validations directly in on_submit causes timing issues because the document state has already transitioned.

How do I fix permission query conditions SQL errors in Frappe?

Fix Frappe permission_query_conditions SQL errors by constructing safe permission SQL with proper escaping. This prevents injection risks and resolves query failures during the get_list hook phase.

What causes extend_doctype_class conflicts in Frappe v16?

extend_doctype_class conflicts in Frappe v16 occur when controller class overrides are missing the super() call. Ensuring super() is called in overrides resolves these lifecycle logic and inheritance conflicts.

How do I resolve NestedSet circular references in Frappe document controllers?

Resolve Frappe NestedSet circular references by diagnosing the controller hook phases affecting tree structure integrity. Apply production-safe hook patterns to prevent corrupt parent-child relationships during save operations.