Troubleshooting

Troubleshooting

Common problems and where to look.

"Permission Denied" on a document

1. Check the user's roles have read permission on the DocType (Role Permissions Manager).
2. Check User Permissions — they may be restricted to specific records.
3. Check the document's Share list — they may need a one-off grant.
4. For "submit" actions specifically: a role can have read but not submit; review per-action checkboxes.

"DoesNotExistError"

The referenced record was deleted, or it was never created.

• Look in the Error Log for the full traceback — it identifies which DocType.
• Check Document Naming Settings for typos in the Naming Series.
• Check if the user has read permission on the linked DocType (a permission filter can make a record "not exist" from their view).

Document import failing silently

Open Data Import → click the failed entry → review the log. Each row's failure reason is listed. Common causes:

• Mandatory field missing
• Link to non-existent record
• Wrong data type for the column

Email not sending

1. Confirm Email Account → Default Outgoing is set.
2. Test SMTP with bench --site mysite email-test --recipient=test@example.com.
3. Check Email Queue for status; SMTP errors are logged there.
4. Verify outbound firewall isn't blocking port 587 / 465.

Scheduler not running

1. bench --site mysite show-pending-jobs — look for stalled jobs.
2. Confirm scheduler process is up (bench restart to refresh).
3. Check Scheduled Job Log for errors.
4. Verify enable_scheduler in common_site_config.json isn't disabled.

Slow performance

• Check Slow Query Log (Frappe Cloud dashboard or MariaDB directly).
• Look for missing DB indexes — usually on filters in heavy reports.
• Profile a request: bench --site mysite enable_profile then load the page; profile output appears in console logs.

Migration failure

• Read the traceback — usually a custom field conflict or a missing patch.
• bench --site mysite migrate --skip-failing to skip and rerun later.
• If hopelessly stuck, restore from backup and re-attempt with the failing app removed.

Error Log is your friend

Almost every framework error leaves a record in Error Log with full traceback. First place to look when something breaks. System Manager → Error Log → filter by today.