ERPNext Troubleshooting: Fix the 12 Most Common Errors (2026)

How do I find the actual error message in ERPNext?

Before fixing anything, read the actual error, not the generic "Something went wrong" screen. ERPNext hides Python tracebacks from users, but it always logs them.

Four ways to find the real error:

1. Browser developer tools: press F12, open the Network tab, reproduce the error and click the failed request (usually a 500). The response holds the traceback.

2. Error Log: open /app/error-log in ERPNext. It lists server-side errors with the full traceback, the time and the method that failed.

3. Bench logs: on the server, tail -100 ~/frappe-bench/logs/frappe.log shows recent errors. For background jobs, check tail -100 ~/frappe-bench/logs/worker.error.log; for the web process, web.error.log.

4. Bench console: bench --site yoursite.com console opens a Python shell in your site's context, useful for re-running the failing operation and seeing the error directly.

How do I fix ERPNext Internal Server Error (500)?

An Internal Server Error means Python raised an unhandled exception. The fix depends on what the traceback says.

Common causes and fixes:

Missing or corrupt site_config.json

Symptom: a 500 on every page, including the login page.

Fix: check that ~/frappe-bench/sites/yoursite.com/site_config.json exists and is valid JSON with at least db_name and db_password. A common cause is editing the file with an editor that adds a byte-order mark or a trailing comma.

cat ~/frappe-bench/sites/yoursite.com/site_config.json
python3 -m json.tool ~/frappe-bench/sites/yoursite.com/site_config.json

If the file is corrupt, restore it from a backup or recreate it with the correct database credentials.

MariaDB connection refused

Symptom: OperationalError: (2002, "Can't connect to local MySQL server") in the traceback.

Fix: MariaDB is not running. Start it:

sudo systemctl start mariadb
sudo systemctl enable mariadb

If MariaDB keeps stopping, check its log (/var/log/mysql/error.log or journalctl -u mariadb). The usual causes are a full disk or InnoDB corruption.

Redis connection error

Symptom: redis.exceptions.ConnectionError: Error connecting to Redis.

Fix: on a production bench, Redis runs under Supervisor as two instances, redis-cache and redis-queue (Socket.IO uses the queue instance since v15). Check and restart them:

sudo supervisorctl status
sudo supervisorctl restart frappe-bench-redis:

Or restart everything: sudo supervisorctl restart all. (Replace frappe-bench with your bench's name.)

Permission errors

Symptom: frappe.exceptions.PermissionError in the traceback, but the user should have access.

Fix: the user's role lacks the permission. Open the Role Permissions Manager, find the DocType named in the error, and check that the role has Read, Write or Create as needed. Don't solve it with Administrator access; fix the role.

How do I fix bench update failures?

bench update is how you keep ERPNext current. When it fails, it usually says why. These are the common patterns.

Git conflict on local changes

Symptom: error: Your local changes to the following files would be overwritten by merge.

Fix: someone edited files inside an app directory. Save the changes, then set them aside and update:

cd ~/frappe-bench/apps/erpnext
git diff > ~/erpnext-local-changes.patch
git stash
cd ~/frappe-bench
bench update

Afterwards, decide whether the changes are still needed. If they are customisations, move them to a custom app; edits to core files break on every update. bench update --reset also clears this error, by hard-resetting every app to the new code and throwing local changes away.

Node.js version mismatch

Symptom: error engine: incompatible with this module or build errors during the asset build.

Fix: check the version each branch needs. v15 needs Node 18 or later; v16 needs Node 24 or later.

node --version

If it is too old, update with nvm (shown for v16):

nvm install 24
nvm use 24
nvm alias default 24
bench setup requirements --node
bench build

Python dependency error

Symptom: ModuleNotFoundError or ImportError after an update.

Fix: the virtual environment is out of sync. Reinstall the Python requirements:

bench setup requirements --python

If the environment itself is broken, rebuild it with the right interpreter (bench setup env --python python3.14 on v16), then reinstall the requirements.

Migration failed

Symptom: the code updates, but bench migrate fails with a database error.

Fix: read the specific error. Common cases:

• Duplicate column: a custom field clashes with a new standard field. Remove the custom field (after copying its data if you need it), then migrate again.
• Missing app or module: an app installed on the site is missing from the bench or on the wrong branch. Get it on the same branch as Frappe, then migrate.
• Lock or timeout on a large table: altering big tables takes time. Run the migration outside working hours with the site in maintenance mode, and check the MariaDB error log for the exact limit hit.

Golden rule: always run bench --site yoursite.com backup --with-files before bench update. If the update goes badly, restore:

bench --site yoursite.com restore ~/frappe-bench/sites/yoursite.com/private/backups/[latest-backup].sql.gz

How do I fix database deadlocks in ERPNext?

Deadlocks look random but aren't. A deadlock happens when two database transactions each wait for a lock the other holds, and ERPNext hits it under particular concurrent-write patterns.

Common deadlock triggers:

1. Bulk stock entries through the API: many stock entries submitted at once by a script or integration. Each one locks rows in the stock ledger, bins and GL entries.

2. Large payment reconciliations: reconciling many invoices in one run updates invoice status, payment entries and GL entries together.

3. Concurrent customer or address updates: an external system syncing customers through /api/resource/Customer while users edit the same records.

The fix pattern:

Serialise the bulk work:

• Submit bulk stock entries in small batches, one batch at a time, instead of all at once. Better still, queue them as background jobs.
• Run payment reconciliation in smaller batches.

Keep concurrency sensible:

• More gunicorn workers mean more concurrent writes. If deadlocks started after you raised the worker count, bring it back down. Set it in the common config, then regenerate the Supervisor config:

bench config set-common-config -c gunicorn_workers 4
bench setup supervisor
sudo supervisorctl reload

Raise the lock wait timeout (relief, not a fix):

# In the MariaDB config, under [mysqld]
innodb_lock_wait_timeout = 120

Restart MariaDB after the change. It gives transactions longer to get their locks but doesn't remove the cause.

See what deadlocked:

# In the MariaDB console
SHOW ENGINE INNODB STATUS\G

The LATEST DETECTED DEADLOCK section shows the two transactions and the tables and rows involved.

How do I fix PDF generation errors in ERPNext?

v15 generates PDFs with wkhtmltopdf. v16 adds a Chrome-based generator and uses it for new print formats; classic formats keep using wkhtmltopdf until v17. Find out which engine is failing before you fix it: in v16, the PDF generator is set on the print format and in Print Settings.

Error 1: "wkhtmltopdf not found"

Fix: wkhtmltopdf is not installed or not on the PATH that Supervisor uses.

which wkhtmltopdf

Install the patched build (below). If it is installed but not found, link it into a directory on Supervisor's PATH, such as /usr/bin.

Error 2: "Invalid wkhtmltopdf version" or unpatched Qt

Fix: Frappe needs wkhtmltopdf 0.12.6 or later with patched Qt. The apt package is often unpatched. Install the build for your OS from the wkhtmltopdf packaging releases, for example on Ubuntu 22.04:

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo apt install ./wkhtmltox_0.12.6.1-3.jammy_amd64.deb

Error 3: broken layout or missing fonts

Fix: install the fonts your print format uses. For invoices with Hindi, Marathi or Tamil text:

sudo apt install fonts-noto fonts-noto-cjk fonts-noto-extra

Also check host_name in site_config.json. wkhtmltopdf fetches CSS and images from this URL, so if it points to localhost while the site runs on a domain, styles won't load.

{
  "host_name": "https://erp.yourcompany.com"
}

Error 4 (v16): Chrome PDFs fail or time out

Fix: the Chrome generator needs Chromium on the server. Install it with:

bench setup-chrome

If the error says "Chromium is not downloaded", the binary path is wrong or the install didn't run in the container that prints. If PDFs hang and return a 504 on early v16 releases, it is a known regression fixed in Frappe v16.24.3; see the v16 Chrome PDF 504 fix.

How do I fix stock and GL ledger mismatches?

A stock-GL mismatch means the stock value in the stock ledger doesn't match the stock accounts in your books. It is the error finance teams fear most.

How to detect it:

Run the Stock and Account Value Comparison report (Stock reports). Any row where stock value and account value differ is a mismatch.

Common causes:

1. Backdated transactions: a stock entry dated months ago changes valuations from that date forward. ERPNext queues a repost; if the repost fails or is stuck, the ledgers diverge.

2. Cancelled-then-amended entries: an interrupted cancel or amend (timeout, server restart) can leave the ledgers out of step.

3. Direct database edits: anyone who edited tabStock Ledger Entry or tabGL Entry directly has broken the chain. Never edit these tables directly.

4. Rounding: occasional small differences from exchange rates and precision settings on multi-currency transactions.

How to fix it:

Step 1: Find the affected items and warehouses in the Stock and Account Value Comparison report.

Step 2: Check for stuck reposts. Open /app/repost-item-valuation and look for entries that are queued or failed. A failed one shows its error; fix that first. See Repost Item Valuation stuck.

Step 3: Repost from the date the mismatch started. Create a new Repost Item Valuation (/app/repost-item-valuation/new) for the item and warehouse, or for a voucher, from that date. ERPNext recalculates stock valuations forward and reposts the GL entries of the affected stock transactions.

Step 4: Repost specific vouchers if needed. For particular invoices, payment entries or journal entries whose ledger entries need regenerating, use Repost Accounting Ledger (/app/repost-accounting-ledger/new): choose the company and list the vouchers.

Step 5: Verify by running the Stock and Account Value Comparison report again.

Prevention:

• Avoid backdated stock transactions; if you must, check that the repost completes.
• Never edit stock or GL tables directly.
• Run the comparison report as part of every month-end close.

For costing problems, see the ERPNext standard costing guide and the landed cost voucher guide. For a submit blocked by "Negative quantity is not allowed", see negative stock in ERPNext; for a count that will not submit or sets the wrong quantity, see Stock Reconciliation; for how stock should flow day to day, see the inventory management guide.

How do I fix ERPNext v16 upgrade errors?

Moving from v15 to v16 is the most error-prone operation in ERPNext right now, because v16 has hard runtime requirements v15 did not. v16 reached its final release on 12 January 2026; Frappe plans to support v15 until the end of 2027, so there is time to do it properly.

Runtime requirements:

(v16 figures from Frappe's pyproject.toml and package.json on the version-16 branch, checked 12 October 2026. For MariaDB and Redis, check the install notes for the branch.)

Error 1: SyntaxError or install failure on an older Python

Symptom: SyntaxError in Frappe code, or pip refusing to install Frappe, after switching to the v16 branch.

Fix: v16 requires Python 3.14. Install it (for example with uv or a Python PPA), then rebuild the bench's environment:

bench setup env --python python3.14
bench setup requirements --python

Error 2: asset build fails

Symptom: bench build fails with esbuild or engine errors after switching to v16.

Fix: upgrade Node.js to 24:

nvm install 24
nvm use 24
nvm alias default 24
bench setup requirements --node
bench build

Error 3: missing app during migration

Symptom: bench migrate fails with Could not find app or a missing-module error.

Fix: every app installed on the site must be on the bench and on the version-16 branch, including Frappe HR (hrms), India Compliance and payments if you use them. Get or switch the missing app, then migrate:

bench get-app [appname] --branch version-16
bench --site yoursite.com migrate

Error 4: custom fields clash with new standard fields

Symptom: a duplicate-column error during migration: a custom field you created on v15 now exists as a standard field in v16.

Fix: before upgrading, list your custom fields (/app/custom-field) and compare them with the v16 release notes. Copy any data you need, remove the clashing custom field, then run bench migrate.

The safe upgrade path (upgrade the runtimes, switch branch, migrate):

1. Back up everything: bench --site yoursite.com backup --with-files
2. Fix all pending errors on v15 first: run bench migrate on v15 and clear any issues
3. Do the whole upgrade on a staging copy before production
4. Upgrade the runtimes: Python 3.14 and Node 24
5. Switch branches: bench switch-to-branch version-16 frappe erpnext hrms (plus your other apps)
6. Rebuild the environment: bench setup env --python python3.14, then bench setup requirements
7. Migrate: bench --site yoursite.com migrate
8. Build assets: bench build, and run bench setup-chrome for the Chrome PDF engine
9. Test the critical flows before letting users in

For the full walkthrough, see the v15 to v16 upgrade guide. If the sidebar or your customised workspaces look different afterwards, the v16 workspace guide shows where the controls moved.

How do I fix ERPNext email sending errors?

Email failures are quiet: invoices don't reach customers, approvers miss notifications, password resets fail. ERPNext sends mail through the Email Accounts you configure.

Error 1: "Email account not configured"

Fix: create an Email Account (/app/email-account/new) with your SMTP details and tick it as the default outgoing account. For Gmail or Google Workspace: smtp.gmail.com, port 587 with TLS, and an app password, because the normal password won't work with two-step verification on.

Error 2: "Authentication failed"

Fix: the password is wrong or was revoked. For Gmail, create a new app password. For other providers, check with them. Update the password on the Email Account.

Error 3: emails stuck in the queue

Symptom: emails sit in the Email Queue (/app/email-queue) as "Not Sent" or "Error".

Fix: check the scheduler and workers are running:

bench doctor
sudo supervisorctl status

If workers are down, sudo supervisorctl restart all. If they are running but mail is stuck, open a failed email in the queue to see its error. Common causes: the provider's rate limit, an attachment too large, or an invalid recipient.

Error 4: emails going to spam

Fix: set SPF, DKIM and DMARC records for the sending domain. Without them, Gmail and Outlook treat your mail as suspect. This is DNS, not ERPNext.

How do I fix ERPNext scheduler and background job errors?

The scheduler runs recurring tasks: email digests, auto-repeat invoices, integration syncs and scheduled reports. When it stops, those tasks stop silently too. Auto-reorder is one of them: if Material Requests stop appearing for items below their reorder level, check the scheduler first.

Error 1: "Scheduler is disabled" or paused

Symptom: recurring tasks stop. Check with:

bench doctor

Fix: enable the scheduler for the site:

bench --site yoursite.com enable-scheduler

A failed bench update can leave sites in maintenance mode with the scheduler paused. After any failed update, check bench doctor, turn maintenance mode off (bench --site yoursite.com set-maintenance-mode off) and make sure the scheduler is back on.

Error 2: background jobs stuck or failing

Symptom: jobs pile up as queued in the background jobs list (/app/rq-job) and never finish.

Fix: restart the workers:

sudo supervisorctl restart all

If jobs keep failing, read the worker error log:

tail -50 ~/frappe-bench/logs/worker.error.log

A job that throws an unhandled exception keeps failing until the cause is fixed; find it in the Error Log and fix that.

Error 3: scheduled jobs never trigger

Fix: on a production bench, the scheduler is a Supervisor process (frappe-bench-frappe-schedule, running bench schedule), not a system cron entry. Check it is running:

sudo supervisorctl status

If it is missing, regenerate the Supervisor config with bench setup supervisor and sudo supervisorctl reload. The Scheduled Job Log (/app/scheduled-job-log) shows what ran and when.

How do I fix ERPNext performance issues?

Slow ERPNext is a symptom, not a single problem. The fix depends on whether the bottleneck is the database, the application server or the browser.

Step 1: find the bottleneck

• Slow pages for everyone: server side (database or application)
• Slow for one user only: browser cache, network, or that user's data volume
• Slow on particular reports: the report's queries need work (the dashboards and reports guide covers when to use Report Builder and when a Query Report)
• Slow since a particular date: a recent change, or data volume crossing a line

Database bottlenecks (the most common):

# Turn on slow query logging, in the MariaDB config under [mysqld]
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2

# Then read it
tail -100 /var/log/mysql/slow.log

Common fixes:

• Run bench --site yoursite.com migrate so standard indexes are in place, and add indexes for the slow queries you found
• Size innodb_buffer_pool_size to a large share of RAM on a server where MariaDB is the main workload (often half or more), leaving room for the workers
• Archive old data only with your accountant's agreement; don't delete submitted documents

Application bottlenecks:

• Tune the gunicorn worker count to the CPU. Gunicorn's own guide suggests (2 × CPU cores) + 1 as a start; see the deadlock section before raising it
• Check both Redis instances are running (sudo supervisorctl status)
• Look for runaway background jobs using CPU: bench doctor and sudo supervisorctl status

Browser bottlenecks:

• Clear the browser cache after an update; old cached files cause odd behaviour
• Disable extensions; some ad blockers interfere with ERPNext's API calls
• Use a current Chrome, Edge or Firefox

For server sizing, see the ERPNext hosting cost guide.

How do I fix ERPNext login issues?

Login failures cause the most panic because they can lock out everyone, including the Administrator.

Error 1: blank login page or "frappe.boot is undefined"

Symptom: the login page is blank, or the console shows frappe.boot is undefined.

Fix: stale built assets or cache. Rebuild and clear:

bench build
bench --site yoursite.com clear-cache
bench --site yoursite.com clear-website-cache
sudo supervisorctl restart all

Ask users to hard-refresh (Ctrl+Shift+R).

Error 2: Administrator password lost

Fix: reset it from the command line:

bench --site yoursite.com set-admin-password [new-password]

Error 3: locked out of two-factor authentication

Symptom: the 2FA code is rejected and the user has lost their authenticator.

Fix: a System Manager can reset the user's OTP secret from the user's record (Reset OTP Secret); the user then sets up their authenticator again at the next login. Two-factor authentication is switched on in System Settings and applied per role. If the System Manager is the one locked out, sign in as Administrator after resetting its password as above.

Error 4: "Your account has been locked and will resume after … seconds"

Symptom: too many failed logins locked the account.

Fix: wait out the lock. By default ERPNext allows 10 consecutive failed attempts and then locks the account for 60 seconds; both numbers are set in System Settings (Allow Consecutive Login Attempts, Allow Login After Fail). If logins keep failing after the wait, the password is the problem: reset it.

How do I fix ERPNext permission errors?

Permission errors show up as "Not permitted" messages, or as users who can't see documents they should.

How ERPNext permissions work:

ERPNext layers permissions: role permissions on each DocType, then user permissions that restrict which records, then sharing of individual documents. Each layer narrows the one before.

Fix 1: the user can't see a DocType at all

Open the Role Permissions Manager, find the DocType and check that one of the user's roles has at least Read. If not, add it.

Fix 2: the user sees the DocType but not certain records

That is a User Permission. Open the User Permission list and look for a restriction on that user. For example, a User Permission limiting "Company" to "Company A" hides documents of "Company B".

Fix 3: the user can't create or submit documents

Check that the role has Create and Submit in the Role Permissions Manager. If the document has a workflow, the user also needs the role allowed to act on the current workflow state.

Fix 4: "Cannot edit after submission"

Submitted documents are locked by design. To change one:

• Cancel and amend: cancel the document and amend it into a new version (the right route for invoices and stock entries)
• Allow on Submit: in Customize Form, mark specific fields as editable after submission

Debugging tip: as Administrator (or a role allowed to impersonate), use Impersonate on the user's record to see exactly what they see. It is faster than guessing which role is wrong; the impersonation is logged and the user is notified.

Frequently asked questions