frappe-errors-permissions

name	frappe-errors-permissions
description	Use when debugging or handling permission errors in Frappe/ERPNext. Prevents broken document access from throwing in permission hooks. Covers PermissionError (403), has_permission hook failures, User Permission restricting too much or too little, perm_level blocking field access, System Manager bypass not working, Guest access denied, sharing permissions not applying, permission_query_conditions breaking get_list, owner-based permissions confusion, Apply User Permission checkbox behavior, and the permission debug workflow using frappe.permissions.get_doc_permissions. Keywords: PermissionError, has_permission, permission_query_conditions,, permission denied, cannot access, user blocked, sharing not working, role not enough. User Permission, perm_level, sharing, guest access, owner permission.
license	MIT
compatibility	Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16.
metadata	{"author":"OpenAEC-Foundation","version":"2.0"}

Permission Error Handling

For permission system overview see frappe-core-permissions. For hook syntax see frappe-syntax-hooks.

---

Quick Diagnostic: Error Message -> Cause -> Fix

Error Message	Cause	Fix
frappe.exceptions.PermissionError	User lacks role or doc-level access	Add role in Role Permissions Manager or grant User Permission
"Not permitted" on document open	has_permission hook returns False or role missing read	Check frappe.permissions.get_doc_permissions(doc, user) output
List view shows 0 records	permission_query_conditions returns overly restrictive SQL	Debug the SQL condition; check User Permissions for the Link field
"Not allowed to access ... for Guest"	Endpoint missing allow_guest=True or DocType lacks Guest read	Add allow_guest=True to @frappe.whitelist()
Field invisible despite role having read	perm_level > 0 on field and role lacks that level	Add role permission row for the specific perm_level
"User Permission restriction" blocking	User Permission on a Link field auto-filters documents	Uncheck "Apply User Permissions" on that role row or add matching User Permission
Sharing not granting access	Sharing adds access but never overrides role absence	User MUST have base role permission; sharing only adds doc-level grants
ignore_permissions has no effect	Flag set after get_doc already checked permissions	Set flags.ignore_permissions = True BEFORE calling save() or insert()
System Manager cannot access	Custom has_permission hook denies without checking role	ALWAYS check for System Manager / Administrator in hook

---

Decision Tree: Where Is the Error?

Permission error occurred
├── Document-level (single doc access)?
│   ├── has_permission hook returning False?
│   │   └── Debug: frappe.permissions.get_doc_permissions(doc, user)
│   ├── User Permission restricting Link field?
│   │   └── Check: frappe.get_all("User Permission", filters={"user": user})
│   ├── perm_level blocking field?
│   │   └── Check: role has permission row for that perm_level
│   └── Sharing not applying?
│       └── Check: user has base role + sharing record exists
├── List-level (0 records in list view)?
│   ├── permission_query_conditions returning bad SQL?
│   │   └── Debug: run condition manually in MariaDB console
│   ├── User Permission auto-filtering?
│   │   └── Check "Apply User Permissions" checkbox on role row
│   └── get_all vs get_list confusion?
│       └── ALWAYS use get_list for user-facing queries
├── API endpoint (403 response)?
│   ├── Missing @frappe.whitelist()?
│   │   └── Add decorator to Python method
│   ├── Missing allow_guest=True?
│   │   └── Add allow_guest parameter for public endpoints
│   └── frappe.only_for() blocking?
│       └── Check user has required role
└── System Manager bypass failing?
    └── Custom hook does not check for System Manager role

---

Permission Hook Errors

has_permission Hook: NEVER Throw

# hooks.py
has_permission = {
    "Sales Order": "myapp.permissions.sales_order_has_permission",
}

# WRONG — Breaks ALL document access
def sales_order_has_permission(doc, user, permission_type):
    if doc.status == "Locked":
        frappe.throw("Locked")  # NEVER do this

# CORRECT — Return False to deny, None to defer
def sales_order_has_permission(doc, user, permission_type):
    """
    ALWAYS wrap in try/except. NEVER throw. NEVER return True.
    Returns: False (deny) or None (defer to standard system).
    """
    try:
        user = user or frappe.session.user
        if user == "Administrator":
            return None

        # ALWAYS check System Manager early
        if "System Manager" in frappe.get_roles(user):
            return None

        # Deny write on locked docs (but allow read)
        if permission_type in ("write", "delete", "cancel"):
            if doc.get("status") == "Locked":
                return False

        return None  # Defer to standard permission system

    except Exception:
        frappe.log_error(frappe.get_traceback(),
            f"has_permission error: {getattr(doc, 'name', 'unknown')}")
        return None  # Safe fallback — defer

Critical rules for has_permission hooks:

• ALWAYS return None to defer, False to deny. NEVER return True — hooks can only restrict, not grant.
• ALWAYS wrap the entire function in try/except. An unhandled exception breaks ALL access to that DocType.
• ALWAYS check for Administrator and System Manager at the top.
• NEVER call frappe.throw() inside this hook.

permission_query_conditions: NEVER Throw

# hooks.py
permission_query_conditions = {
    "Sales Order": "myapp.permissions.sales_order_query",
}

# WRONG — Breaks list view for all users
def sales_order_query(user):
    if not user:
        frappe.throw("User required")  # NEVER do this
    return f"owner = '{user}'"  # SQL injection!

# CORRECT — Return SQL string or empty string
def sales_order_query(user):
    """
    ALWAYS return a string. Empty string = no restriction.
    ALWAYS use frappe.db.escape(). ALWAYS wrap in try/except.
    """
    try:
        user = user or frappe.session.user
        if user == "Administrator":
            return ""
        if "System Manager" in frappe.get_roles(user):
            return ""

        return f"`tabSales Order`.owner = {frappe.db.escape(user)}"

    except Exception:
        frappe.log_error(frappe.get_traceback(), "Query conditions error")
        # SAFE FALLBACK: most restrictive
        return f"`tabSales Order`.owner = {frappe.db.escape(frappe.session.user)}"

Critical rules for permission_query_conditions:

• NEVER throw errors — return "1=0" to deny all or a restrictive SQL string.
• ALWAYS use frappe.db.escape() for every user-supplied value.
• This hook ONLY affects frappe.get_list() / frappe.db.get_list(). It does NOT affect frappe.get_all() / frappe.db.get_all().

---

User Permission Errors

Too Restrictive: Records Disappear

Error: User can't see any Sales Orders despite having Sales User role.
Cause: A User Permission for "Company" exists, and "Apply User Permissions"
       is checked on the Sales Order role row. Sales Order has a Company
       Link field, so ALL Sales Orders are filtered by that Company value.

Debug steps:

# Step 1: Check what User Permissions exist
frappe.get_all("User Permission",
    filters={"user": "[e-mail]"},
    fields=["allow", "for_value", "applicable_for"])

# Step 2: Check if Apply User Permissions is checked
frappe.get_all("DocPerm",
    filters={"parent": "Sales Order", "role": "Sales User"},
    fields=["role", "permlevel", "apply_user_permissions"])  # [v14]

# Step 3: Check effective permissions on a specific doc
from frappe.permissions import get_doc_permissions
perms = get_doc_permissions(frappe.get_doc("Sales Order", "SO-001"), "[e-mail]")

Fix patterns:

• Remove overly broad User Permissions that filter unintended DocTypes.
• Use the applicable_for field [v14+] to limit which DocType a User Permission applies to.
• Uncheck "Apply User Permissions" on the role permission row if blanket filtering is unwanted.

Too Permissive: User Sees Everything

Error: User Permission set for Territory = "North" but user sees all territories.
Cause: "Apply User Permissions" is NOT checked on the role permission row,
       or the DocType has no Link field for Territory.

Fix: Ensure the role permission row has "Apply User Permissions" checked AND the DocType has a Link field to the restricted DocType.

---

perm_level Errors

Error: Field "cost_center" is invisible despite user having read permission.
Cause: Field has permlevel=1 but role only has permission for permlevel=0.

# Check which perm_levels a role has access to
frappe.get_all("DocPerm",
    filters={"parent": "Sales Invoice", "role": "Accounts User"},
    fields=["permlevel", "read", "write"])

Fix: Add a new row in the DocType's Permission table for the role at the required permlevel.

---

Sharing Permission Errors

Error: Document shared with user but user still gets PermissionError.
Cause: User has NO base role permission on the DocType. Sharing only
       supplements — it never replaces role-based permissions.

# Share a document (user MUST already have a role with at least read)
frappe.share.add("Sales Order", "SO-001", "[e-mail]",
    read=1, write=1, share=1)

# Check if sharing grants access
frappe.share.get_sharing_permissions("Sales Order", "SO-001", "[e-mail]")

Rules:

• ALWAYS ensure the user has at least one role with read permission on the DocType before sharing.
• Sharing adds document-level grants on top of role permissions.
• [v15+] frappe.share.add accepts notify=1 to send email notification.

---

Guest Access Errors

Error: "Not permitted" for unauthenticated users.
Cause: DocType has no Guest read permission, or API missing allow_guest.

Fix for web pages / portal:

# Add Guest read permission in DocType Permission table
# Role: Guest, Level: 0, Read: checked

Fix for API endpoints:

@frappe.whitelist(allow_guest=True)
def public_endpoint():
    # ALWAYS validate input — guest endpoints are exposed to the internet
    pass

NEVER grant Guest write/create/delete permissions unless the DocType is specifically designed for public submission (e.g., Web Form backend).

---

Debug Workflow: frappe.permissions

import frappe
from frappe.permissions import get_doc_permissions

# Get all effective permissions for a user on a document
doc = frappe.get_doc("Sales Order", "SO-001")
perms = get_doc_permissions(doc, user="[e-mail]")
# Returns dict: {"read": 1, "write": 0, "create": 0, ...}

# Check specific permission with full context
frappe.has_permission("Sales Order", ptype="write",
    doc="SO-001", user="[e-mail]", throw=False)

# List all roles for a user
frappe.get_roles("[e-mail]")

# Check User Permissions
frappe.get_all("User Permission",
    filters={"user": "[e-mail]"},
    fields=["allow", "for_value", "applicable_for", "is_default"])

---

Critical Rules

ALWAYS

1. Wrap permission hooks in try/except — unhandled errors break all access
2. Return None (not True) in has_permission — hooks can only deny
3. Use frappe.db.escape() in query conditions — prevent SQL injection
4. Check System Manager / Administrator first in custom hooks
5. Use frappe.has_permission(throw=True) for endpoint permission checks
6. Use get_list (not get_all) for user-facing queries — get_all bypasses permissions
7. Log permission denials for security audit with frappe.log_error()

NEVER

1. Throw in has_permission or permission_query_conditions — breaks access entirely
2. Return True in has_permission — has no effect, hooks can only restrict
3. Use string formatting for SQL — use frappe.db.escape() to prevent injection
4. Grant Guest write/delete permissions — security risk
5. Use ignore_permissions without documenting why — creates audit gaps
6. Assume sharing replaces role permissions — sharing only supplements

---

Reference Files

File	Contents
references/patterns.md	Complete hook patterns, query conditions, API endpoints
references/examples.md	Full working examples with hooks.py configuration
references/anti-patterns.md	15 common mistakes with wrong/correct comparisons

---

See Also

• frappe-core-permissions — Permission system architecture
• frappe-errors-api — API error handling (401/403/404)
• frappe-errors-hooks — Hook error handling patterns
• frappe-syntax-hooks — Hook registration syntax