---
title: "Troubleshooting"
space: "Frappe Framework"
url: "https://www.prilk.com/docs/frappe-framework/troubleshooting"
updated: "2026-05-14"
---

## 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**.