Frappe Framework

Frappe Framework

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.

Last updated 2 months ago
Was this helpful?
Thanks!