ERPNext Hooks - Error Handling

This skill covers error handling patterns for hooks.py configurations. For syntax, see erpnext-syntax-hooks . For implementation workflows, see erpnext-impl-hooks .

Version: v14/v15/v16 compatible

Hooks Error Handling Overview

┌─────────────────────────────────────────────────────────────────────┐ │ HOOKS HAVE UNIQUE ERROR HANDLING CHARACTERISTICS │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ✅ Full Python power (try/except, raise) │ │ ⚠️ Multiple handlers in chain - one failure affects others │ │ ⚠️ Some hooks are silent (scheduler, permission_query) │ │ ⚠️ Transaction behavior varies by hook type │ │ │ │ Key differences from controllers: │ │ • doc_events runs AFTER controller methods │ │ • Multiple apps can register handlers (order matters!) │ │ • Scheduler has NO user feedback - logging is critical │ │ • Permission hooks should NEVER throw errors │ │ │ └─────────────────────────────────────────────────────────────────────┘

Main Decision: Error Handling by Hook Type

┌─────────────────────────────────────────────────────────────────────────┐ │ WHICH HOOK TYPE ARE YOU USING? │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ► doc_events (validate, on_update, on_submit, etc.) │ │ └─► Same as controllers: frappe.throw() rolls back in validate │ │ └─► Multiple handlers: first error stops chain │ │ └─► Isolate non-critical operations in try/except │ │ │ │ ► scheduler_events (daily, hourly, cron) │ │ └─► NO user feedback - frappe.log_error() is essential │ │ └─► ALWAYS use try/except around operations │ │ └─► MUST call frappe.db.commit() manually │ │ │ │ ► permission_query_conditions │ │ └─► NEVER throw errors - return empty string on error │ │ └─► Silent failures break list views │ │ └─► Log errors but return safe fallback │ │ │ │ ► has_permission │ │ └─► NEVER throw errors - return False on error │ │ └─► Return None to defer to default permission │ │ │ │ ► override_doctype_class / extend_doctype_class │ │ └─► ALWAYS call super() in try/except │ │ └─► Parent errors should usually propagate │ │ │ │ ► extend_bootinfo │ │ └─► Errors break page load entirely! │ │ └─► ALWAYS wrap in try/except with fallback │ │ │ └─────────────────────────────────────────────────────────────────────────┘

doc_events Error Handling

Transaction Behavior (Same as Controllers)

Event frappe.throw() Effect

validate

✅ Full rollback - document NOT saved

before_save

✅ Full rollback - document NOT saved

on_update

⚠️ Document IS saved, error shown

after_insert

⚠️ Document IS saved, error shown

on_submit

⚠️ docstatus=1, error shown

on_cancel

⚠️ docstatus=2, error shown

Multiple Handler Chain

hooks.py - Multiple apps can register handlers

App A

doc_events = { "Sales Invoice": { "validate": "app_a.events.validate_si" # Runs first } }

App B

doc_events = { "Sales Invoice": { "validate": "app_b.events.validate_si" # Runs second } }

If App A throws error, App B's handler NEVER runs!

Pattern: Validate Handler

myapp/events/sales_invoice.py

import frappe from frappe import _

def validate(doc, method=None): """Validate handler with proper error handling.""" errors = []

# Collect validation errors
if doc.grand_total < 0:
    errors.append(_("Total cannot be negative"))

if doc.custom_field and not doc.customer:
    errors.append(_("Customer required when custom field is set"))

# Throw all at once
if errors:
    frappe.throw("<br>".join(errors))

Pattern: on_update Handler (Isolated Operations)

def on_update(doc, method=None): """Post-save handler with isolated operations.""" # Critical operation - let errors propagate update_linked_records(doc)

# Non-critical operations - isolate errors
try:
    send_notification(doc)
except Exception:
    frappe.log_error(
        frappe.get_traceback(),
        f"Notification failed for {doc.name}"
    )

try:
    sync_to_external(doc)
except Exception:
    frappe.log_error(
        frappe.get_traceback(),
        f"External sync failed for {doc.name}"
    )

scheduler_events Error Handling

Critical: No User Feedback!

┌─────────────────────────────────────────────────────────────────────┐ │ ⚠️ SCHEDULER TASKS HAVE NO USER - LOGGING IS ESSENTIAL │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ • No one sees frappe.throw() - task just fails silently │ │ • No automatic email on failure (unless configured) │ │ • frappe.log_error() is your ONLY debugging tool │ │ • Always commit changes manually │ │ │ └─────────────────────────────────────────────────────────────────────┘

Pattern: Scheduler Task with Error Handling

myapp/tasks.py

import frappe

def daily_sync(): """Daily sync task with comprehensive error handling.""" results = { "processed": 0, "errors": [] }

try:
    # Get records to process (ALWAYS with limit!)
    records = frappe.get_all(
        "Sales Invoice",
        filters={"sync_status": "Pending"},
        limit=500
    )
    
    for record in records:
        try:
            process_record(record.name)
            results["processed"] += 1
        except Exception as e:
            results["errors"].append(f"{record.name}: {str(e)}")
            frappe.log_error(
                frappe.get_traceback(),
                f"Sync error: {record.name}"
            )
    
    # REQUIRED: Commit changes
    frappe.db.commit()
    
except Exception as e:
    # Log fatal errors
    frappe.log_error(
        frappe.get_traceback(),
        "Daily Sync Fatal Error"
    )
    return

# Log summary
if results["errors"]:
    summary = f"Processed: {results['processed']}, Errors: {len(results['errors'])}"
    frappe.log_error(
        summary + "\n\n" + "\n".join(results["errors"][:50]),
        "Daily Sync Summary"
    )

Pattern: Scheduler with Batch Commits

def process_large_dataset(): """Process large dataset with periodic commits.""" BATCH_SIZE = 100

try:
    records = frappe.get_all("Item", limit=5000)
    total = len(records)
    
    for i in range(0, total, BATCH_SIZE):
        batch = records[i:i + BATCH_SIZE]
        
        for record in batch:
            try:
                update_item(record.name)
            except Exception:
                frappe.log_error(
                    frappe.get_traceback(),
                    f"Item update error: {record.name}"
                )
        
        # Commit after each batch
        frappe.db.commit()
        
except Exception:
    frappe.log_error(frappe.get_traceback(), "Batch Processing Error")

Permission Hooks Error Handling

permission_query_conditions - NEVER Throw!

❌ WRONG - Breaks list view entirely!

def query_conditions(user): if not user: frappe.throw("User required") # DON'T DO THIS! return f"owner = '{user}'"

✅ CORRECT - Return safe fallback

def query_conditions(user): """Permission query with error handling.""" try: if not user: user = frappe.session.user

    if "System Manager" in frappe.get_roles(user):
        return ""  # No restrictions
    
    return f"`tabSales Invoice`.owner = {frappe.db.escape(user)}"
    
except Exception:
    frappe.log_error(
        frappe.get_traceback(),
        "Permission Query Error"
    )
    # Safe fallback - restrict to own records
    return f"`tabSales Invoice`.owner = {frappe.db.escape(frappe.session.user)}"

has_permission - NEVER Throw!

❌ WRONG - Breaks document access!

def has_permission(doc, user=None, permission_type=None): if doc.status == "Locked": frappe.throw("Document is locked") # DON'T DO THIS!

✅ CORRECT - Return boolean or None

def has_permission(doc, user=None, permission_type=None): """Document permission check with error handling.""" try: user = user or frappe.session.user

    # Deny access to locked documents
    if doc.status == "Locked" and permission_type == "write":
        return False
    
    # Custom logic
    if permission_type == "delete":
        if doc.has_linked_records():
            return False
    
    # Return None to defer to default permission system
    return None
    
except Exception:
    frappe.log_error(
        frappe.get_traceback(),
        f"Permission check error: {doc.name}"
    )
    # Safe fallback - defer to default
    return None

Override Hooks Error Handling

override_doctype_class

myapp/overrides.py

from erpnext.selling.doctype.sales_order.sales_order import SalesOrder import frappe from frappe import _

class CustomSalesOrder(SalesOrder): def validate(self): """Override with proper error handling.""" # ALWAYS call parent first in try/except try: super().validate() except frappe.ValidationError: # Re-raise validation errors raise except Exception as e: frappe.log_error(frappe.get_traceback(), "Parent Validate Error") raise

    # Custom validation
    self.custom_validate()

def custom_validate(self):
    if self.custom_approval_required and not self.custom_approved:
        frappe.throw(_("Approval required before saving"))

extend_doctype_class (V16+)

myapp/extends.py

import frappe from frappe import _

class SalesOrderExtend: """Extension class - only add new methods."""

def custom_approval_check(self):
    """New method with error handling."""
    try:
        if not self.custom_approver:
            frappe.throw(_("Approver not set"))
        
        approver = frappe.get_doc("User", self.custom_approver)
        if not approver.enabled:
            frappe.throw(_("Approver is disabled"))
            
    except frappe.DoesNotExistError:
        frappe.throw(_("Approver not found"))

extend_bootinfo Error Handling

Critical: Errors Break Page Load!

❌ WRONG - Unhandled error breaks desk entirely!

def extend_boot(bootinfo): settings = frappe.get_single("My Settings") # What if it doesn't exist? bootinfo.my_config = settings.config

✅ CORRECT - Always handle errors

def extend_boot(bootinfo): """Extend bootinfo with error handling.""" try: if frappe.db.exists("My Settings", "My Settings"): settings = frappe.get_single("My Settings") bootinfo.my_config = settings.config or {} else: bootinfo.my_config = {}

except Exception:
    frappe.log_error(
        frappe.get_traceback(),
        "Bootinfo Extension Error"
    )
    # Safe fallback
    bootinfo.my_config = {}

Critical Rules

✅ ALWAYS

• Use try/except in scheduler tasks - No user feedback otherwise

• Call frappe.db.commit() in scheduler - Changes aren't auto-saved

• Return safe fallbacks in permission hooks - Never throw

• Call super() in override classes - Preserve parent behavior

• Log errors with context - Include document name, operation

• Wrap extend_bootinfo in try/except - Errors break page load

❌ NEVER

• Don't throw in permission_query_conditions - Breaks list views

• Don't throw in has_permission - Breaks document access

• Don't assume single handler - Multiple apps can register

• Don't commit in doc_events - Framework handles transactions

• Don't ignore scheduler errors - They fail silently

Quick Reference: Error Handling by Hook

Hook Type Can Throw? Commit? Key Pattern

doc_events (validate) ✅ YES ❌ NO Collect errors, throw once

doc_events (on_update) ⚠️ Careful ❌ NO Isolate non-critical ops

scheduler_events ❌ Pointless ✅ YES Try/except + log_error

permission_query_conditions ❌ NEVER ❌ NO Return "" on error

has_permission ❌ NEVER ❌ NO Return None on error

extend_bootinfo ❌ NEVER ❌ NO Try/except + fallback

override class ✅ YES ❌ NO super() + re-raise

Reference Files

File Contents

references/patterns.md

Complete error handling patterns

references/examples.md

Full working examples

references/anti-patterns.md

Common mistakes to avoid

See Also

• erpnext-syntax-hooks

• Hooks syntax

• erpnext-impl-hooks

• Implementation workflows

• erpnext-errors-controllers

• Controller error handling

• erpnext-errors-serverscripts

• Server Script error handling