┌─────────────────────────────────────────────────────────────────────┐
│ PERMISSION ERRORS REQUIRE SPECIAL HANDLING                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ Permission Hooks (has_permission, permission_query_conditions):     │
│ ⚠️ NEVER throw errors - return False or empty string                │
│ ⚠️ Errors break document access and list views                      │
│ ⚠️ Always provide safe fallbacks                                    │
│                                                                     │
│ Permission Checks in Code:                                          │
│ ✅ Use frappe.has_permission() before operations                    │
│ ✅ Use throw=True for automatic error handling                      │
│ ✅ Catch frappe.PermissionError for custom handling                 │
│                                                                     │
│ API Endpoints:                                                      │
│ ✅ frappe.only_for() for role-restricted endpoints                  │
│ ✅ doc.has_permission() before document operations                  │
│ ✅ Return proper HTTP 403 for access denied                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Main Decision: Where Is the Permission Check?

┌─────────────────────────────────────────────────────────────────────────┐
│ WHERE ARE YOU HANDLING PERMISSIONS?                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│ ► has_permission hook (hooks.py)                                        │
│   └─► NEVER throw - return False to deny, None to defer                 │
│   └─► Wrap in try/except, log errors, return None on failure            │
│                                                                         │
│ ► permission_query_conditions hook (hooks.py)                           │
│   └─► NEVER throw - return SQL condition or empty string                │
│   └─► Wrap in try/except, return restrictive fallback on failure        │
│                                                                         │
│ ► Whitelisted method / API endpoint                                     │
│   └─► Use frappe.has_permission() with throw=True                       │
│   └─► Or catch PermissionError for custom response                      │
│   └─► Use frappe.only_for() for role-restricted endpoints               │
│                                                                         │
│ ► Controller method                                                     │
│   └─► Use doc.has_permission() or doc.check_permission()                │
│   └─► Let PermissionError propagate for standard handling               │
│                                                                         │
│ ► Client Script                                                         │
│   └─► Handle in frappe.call error callback                              │
│   └─► Check exc type for PermissionError                                │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Permission Hook Error Handling

has_permission - NEVER Throw!

# ❌ WRONG - Breaks document access!
def has_permission(doc, ptype, user):
    if doc.status == "Locked":
        frappe.throw("Document is locked")  # DON'T DO THIS!

# ✅ CORRECT - Return False to deny, None to defer
def has_permission(doc, ptype, user):
    """
    Custom permission check.
    
    Returns:
        None: Defer to standard permission system
        False: Deny permission
        
    NEVER return True - hooks can only deny, not grant.
    """
    try:
        user = user or frappe.session.user
        
        # Deny editing locked documents
        if ptype == "write" and doc.get("status") == "Locked":
            if "System Manager" not in frappe.get_roles(user):
                return False
        
        # Deny access to confidential documents
        if doc.get("is_confidential"):
            allowed_users = get_allowed_users(doc.name)
            if user not in allowed_users:
                return False
        
        # ALWAYS return None to defer to standard checks
        return None
        
    except Exception:
        frappe.log_error(
            frappe.get_traceback(),
            f"Permission check error: {doc.name if hasattr(doc, 'name') else 'unknown'}"
        )
        # Safe fallback - defer to standard system
        return None

permission_query_conditions - NEVER Throw!

# ❌ WRONG - Breaks list views!
def query_conditions(user):
    if not user:
        frappe.throw("User required")
    return f"owner = '{user}'"  # Also SQL injection!

# ✅ CORRECT - Return safe SQL condition
def query_conditions(user):
    """
    Return SQL WHERE clause fragment for list filtering.
    
    Returns:
        str: SQL condition (empty string for no restriction)
        
    NEVER throw errors - return restrictive fallback.
    """
    try:
        if not user:
            user = frappe.session.user
        
        roles = frappe.get_roles(user)
        
        # Admins see all
        if "System Manager" in roles:
            return ""
        
        # Managers see team records
        if "Sales Manager" in roles:
            team_users = get_team_users(user)
            if team_users:
                escaped = ", ".join([frappe.db.escape(u) for u in team_users])
                return f"`tabSales Order`.owner IN ({escaped})"
        
        # Default: own records only
        return f"`tabSales Order`.owner = {frappe.db.escape(user)}"
        
    except Exception:
        frappe.log_error(
            frappe.get_traceback(),
            f"Permission query error for {user}"
        )
        # SAFE FALLBACK: Most restrictive - own records only
        return f"`tabSales Order`.owner = {frappe.db.escape(frappe.session.user)}"

Permission Check Error Handling

Pattern 1: Check Before Action (Recommended)

@frappe.whitelist()
def update_order_status(order_name, new_status):
    """Update order status with permission check."""
    # Check document exists
    if not frappe.db.exists("Sales Order", order_name):
        frappe.throw(
            _("Sales Order {0} not found").format(order_name),
            exc=frappe.DoesNotExistError
        )
    
    # Check permission - throws automatically
    frappe.has_permission("Sales Order", "write", order_name, throw=True)
    
    # Now safe to proceed
    frappe.db.set_value("Sales Order", order_name, "status", new_status)
    
    return {"status": "success"}

Pattern 2: Custom Permission Error Response

@frappe.whitelist()
def sensitive_operation(doc_name):
    """Operation with custom permission error handling."""
    try:
        doc = frappe.get_doc("Sensitive Doc", doc_name)
        doc.check_permission("write")
        
    except frappe.DoesNotExistError:
        frappe.throw(
            _("Document not found"),
            exc=frappe.DoesNotExistError
        )
        
    except frappe.PermissionError:
        # Log attempted access
        frappe.log_error(
            f"Unauthorized access attempt: {doc_name} by {frappe.session.user}",
            "Security Alert"
        )
        # Custom error message
        frappe.throw(
            _("You don't have permission to perform this action. This incident has been logged."),
            exc=frappe.PermissionError
        )
    
    # Proceed with operation
    return process_document(doc)

Pattern 3: Role-Restricted Endpoint

@frappe.whitelist()
def admin_dashboard_data():
    """Endpoint restricted to specific roles."""
    # This throws PermissionError if user lacks role
    frappe.only_for(["System Manager", "Dashboard Admin"])
    
    # Only reaches here if authorized
    return compile_dashboard_data()


@frappe.whitelist()
def manager_report():
    """Endpoint with graceful role check."""
    allowed_roles = ["Sales Manager", "General Manager", "System Manager"]
    user_roles = frappe.get_roles()
    
    if not any(role in user_roles for role in allowed_roles):
        frappe.throw(
            _("This report is only available to managers"),
            exc=frappe.PermissionError
        )
    
    return generate_report()

Error Response Patterns

Standard Permission Error

# Uses frappe.PermissionError - returns HTTP 403
frappe.throw(
    _("You don't have permission to access this resource"),
    exc=frappe.PermissionError
)

Permission Error with Context

def check_access(doc):
    """Check access with helpful error message."""
    if not doc.has_permission("read"):
        owner_name = frappe.db.get_value("User", doc.owner, "full_name")
        frappe.throw(
            _("This document belongs to {0}. You can only view your own documents.").format(owner_name),
            exc=frappe.PermissionError
        )

Soft Permission Denial (No Error)

@frappe.whitelist()
def get_dashboard_widgets():
    """Return widgets based on user permissions."""
    widgets = []
    
    # Add widgets based on permissions
    if frappe.has_permission("Sales Order", "read"):
        widgets.append(get_sales_widget())
    
    if frappe.has_permission("Purchase Order", "read"):
        widgets.append(get_purchase_widget())
    
    if frappe.has_permission("Employee", "read"):
        widgets.append(get_hr_widget())
    
    # No error if no widgets - just return empty
    return widgets

Client-Side Permission Error Handling

JavaScript Error Handling

// Handle permission errors in frappe.call
frappe.call({
    method: "myapp.api.sensitive_operation",
    args: { doc_name: "DOC-001" },
    callback: function(r) {
        if (r.message) {
            frappe.show_alert({
                message: __("Operation completed"),
                indicator: "green"
            });
        }
    },
    error: function(r) {
        // Check if it's a permission error
        if (r.exc_type === "PermissionError") {
            frappe.msgprint({
                title: __("Access Denied"),
                message: __("You don't have permission to perform this action."),
                indicator: "red"
            });
        } else {
            // Generic error handling
            frappe.msgprint({
                title: __("Error"),
                message: r.exc || __("An error occurred"),
                indicator: "red"
            });
        }
    }
});

Permission Check Before Action

// Check permission before showing button
frappe.ui.form.on("Sales Order", {
    refresh: function(frm) {
        // Only show button if user has write permission
        if (frm.doc.docstatus === 0 && frappe.perm.has_perm("Sales Order", 0, "write")) {
            frm.add_custom_button(__("Special Action"), function() {
                perform_special_action(frm);
            });
        }
    }
});

// Or use frappe.call to check server-side
frappe.call({
    method: "frappe.client.has_permission",
    args: {
        doctype: "Sales Order",
        docname: frm.doc.name,
        ptype: "write"
    },
    async: false,
    callback: function(r) {
        if (r.message) {
            // Has permission - show button
        }
    }
});

Critical Rules

✅ ALWAYS

Return None in has_permission hooks - Never return True
Use frappe.db.escape() in query conditions - Prevent SQL injection
Wrap hooks in try/except - Errors break access entirely
Log permission errors - Security audit trail
Use throw=True in permission checks - Automatic error handling
Provide helpful error messages - Tell users what they can do

❌ NEVER

Don't throw in permission hooks - Return False instead
Don't use string concatenation in SQL - SQL injection risk
Don't return True in has_permission - Hooks can only deny
Don't ignore permission errors - Security risk
Don't expose sensitive info in errors - Security risk

Quick Reference: Permission Error Handling

Context	Error Method	Fallback
has_permission hook	Return False	Return None
permission_query_conditions	Return restrictive SQL	Own records filter
Whitelisted method	frappe.throw(exc=PermissionError)	N/A
Controller	doc.check_permission()	Let propagate
Client Script	error callback	Show user message

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

Main Decision: Where Is the Permission Check?

Permission Hook Error Handling

has_permission - NEVER Throw!

permission_query_conditions - NEVER Throw!

Permission Check Error Handling

Pattern 1: Check Before Action (Recommended)

Pattern 2: Custom Permission Error Response

Pattern 3: Role-Restricted Endpoint

Error Response Patterns

Standard Permission Error

Permission Error with Context

Soft Permission Denial (No Error)

Client-Side Permission Error Handling

JavaScript Error Handling

Permission Check Before Action

Critical Rules

✅ ALWAYS

❌ NEVER

Quick Reference: Permission Error Handling

Reference Files

See Also

erpnext-errors-permissions

ERPNext Permissions - Error Handling

Permission Error Handling Overview