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