Most ERPNext troubleshooting content repeats the same six generic fixes — clear cache, rebuild, bench update --reset. They work for the common case. They don't work for the five bugs below, because each one has a root cause the generic advice never touches. I pulled these straight from GitHub Issues and the Frappe forum, verified the exact error text and fix against the source thread, and did not invent or approximate any of it.
ERPNext and the underlying Frappe framework are actively developed — hundreds of issues open and close on GitHub every month, and the forum fills with reports that look identical to a common error but resolve completely differently underneath. If you've already tried the standard fix for one of these and it didn't stick, one of the five below is probably why.
Why does "frappe.boot is undefined" survive a cache clear?
frappe.boot is undefined survives a cache clear when the root cause is a missing currency value in System Settings, not stale JavaScript. The standard fix — bench build, clear-cache, clear-website-cache, restart — resolves the majority of blank-login-page cases, which is why it's the default advice everywhere including our own /learn/troubleshoot/ guide. But one documented case on the Frappe forum kept failing after every one of those steps.
The actual cause: System Settings had no currency field set. Frappe's boot sequence reads that field on every page load, and when it's absent the value silently defaults to None, which cascades into the JavaScript errors that leave the login page blank. This particular manifestation is unusual — a framework fix for improper None parsing in boot initialization had already been merged — which is exactly why it's worth documenting: it's the case the mainstream fix doesn't cover.
The fix, once you've confirmed cache-clearing didn't work:
INSERT INTO `tabSingles` (`doctype`, `field`, `value`)
VALUES ('System Settings', 'currency', 'USD');
Then rebuild:
bench --site yoursite.com clear-cache
bench build
bench restart
Skimmable summary: if bench build + clear-cache doesn't fix a blank login page showing frappe.boot is undefined, check whether System Settings has a currency value set — a missing one breaks boot initialization in a way cache-clearing can't touch.
Why does ERPNext say "No module named 'erpnext'" even though it's installed?
ModuleNotFoundError: No module named 'erpnext' appears despite a working install when the app's registration is corrupted — a Python virtual environment resync (the standard fix) won't touch it. Our troubleshoot pillar covers the common version of this error, where bench setup env and reinstalling the Python dependencies fixes it. A separate, documented case on the Frappe forum had a working install that still threw this exact error in the browser after every standard attempt.
The difference: this wasn't a dependency problem. The app was listed as installed in apps.txt but its registration in the site's app state was inconsistent — a state that survives bench migrate, clear-cache --force, and even bench update --reset.
The fix that actually resolved it, in order:
# 1. Remove stale locks
rm sites/frontend/locks/*
# 2. Remove and re-register the app
# (edit sites/apps.txt to remove the erpnext line, then:)
bench get erpnext
bench --site frontend install-app erpnext
bench --site frontend migrate
bench restart
If that doesn't resolve it, the forum thread's last resort was bench --site frontend reinstall — which wipes the site database, so only use it with a recent backup in hand. Docker users hit a variant of this where bench get erpnext needs to run separately on every container in the stack, not just one.
Skimmable summary: "No module named 'erpnext'" with a genuinely working install is an app-registration problem, not a dependency problem — the fix touches apps.txt and locks, not the Python environment.
Why does the Frappe scheduler silently stop firing jobs?
The Frappe scheduler goes silent — no errors logged, jobs simply never run — when the database timezone and the application container's timezone disagree, even though bench doctor reports the scheduler as enabled. Our troubleshoot pillar's scheduler section covers the two common causes: the scheduler getting disabled by a failed bench update, and the system cron entry going missing. Neither explains a scheduler that reports itself as healthy while doing nothing.
A GitHub issue on the core Frappe repo documents the actual mechanism: enqueue() checks is_event_due() before running a job, and when the database timezone differs from the container's timezone, the scheduler can write job timestamps into the future — 08:46 tomorrow when it's 23:44 tonight, for instance. Because the timestamp is technically valid, is_event_due() returns False forever, and the job silently never fires again. No error, no log entry — email queues just pile up marked "Not Sent" and scheduled reports stop generating.
Immediate workaround — force one job to run and confirm the theory:
doc = frappe.get_doc("Scheduled Job Type", "queue.flush")
doc.enqueue(force=True)
frappe.db.commit()
The actual fix is aligning the timezones — set MariaDB to UTC explicitly in my.cnf:
[mysqld]
default-time-zone = '+00:00'
Then restart MariaDB and verify new job timestamps land correctly.
Skimmable summary: a scheduler that reports "enabled" but does nothing is a timezone mismatch between MariaDB and the app container, not a disabled scheduler — force one job to confirm, then fix the database timezone.
Why does bench update keep blocking on "local changes in app hrms"?
"Cannot proceed with update: You have local changes in app 'hrms' that are not committed" recurs after every git stash because Yarn rewrites yarn.lock on its own during every dependency resolution — stashing doesn't stop it from happening again next time. This looks identical to the ordinary "uncommitted customisation" case our troubleshoot pillar covers, where you've edited a core file directly. The HRMS-specific version is different: nobody edited anything. Yarn did.
Every time bench update runs, Yarn resolves JavaScript dependencies for the HRMS app and updates yarn.lock to reflect the resolution — which Git then flags as an uncommitted local change, blocking the update. git stash clears it for one run, but the next update triggers the same rewrite and the same block.
The fix that actually stops the cycle:
cd ~/frappe-bench/apps/hrms
git restore yarn.lock
bench update
git restore discards the file back to its committed state rather than stashing a change that Yarn will just recreate — which is why it holds where git stash and even git reset --hard only fix the symptom for one run.
Skimmable summary: if git stash clears the HRMS "local changes" block but it comes back on the very next update, the file being flagged is yarn.lock, rewritten by Yarn itself — git restore yarn.lock fixes it for good, git stash doesn't.
Why is the General Ledger empty after a Frappe Cloud deploy, with a healthy database?
A General Ledger that shows no transactions and transactional doctypes (Sales Orders, Quotations, Invoices) that won't open after a deploy — while the database itself checks out fine — points to a deployment synchronisation failure, not data loss. This is a documented case where an automatic Frappe Cloud deploy was interrupted by an upstream network drop mid-way through.
The symptoms were distinctive: list views worked normally, but opening any transactional document failed. The General Ledger returned empty. The Insights app came back "not found." Database connectivity and the underlying tables were verified intact. That combination — data present, application behaviour broken — is the signature of an incomplete deploy: the runtime environment, compiled static assets, and database migrations ended up out of sync with each other, even though none of them were individually corrupted.
What to check before assuming data loss:
- Confirm the database is actually reachable and tables are populated (
bench mariadb, spot-check a known transaction). - Check the deploy log for a mid-deploy interruption rather than a clean failure.
- Trigger a fresh, complete redeploy rather than trying to patch the partial one — a deployment-sync failure needs a clean re-run, not incremental fixes.
If you're self-hosted rather than on Frappe Cloud, the equivalent check is confirming bench build completed fully and bench migrate ran to completion without an interrupted process in between.
Skimmable summary: forms broken and GL empty with a verified-healthy database after a deploy is a sync failure between runtime, assets, and migrations — re-deploy cleanly rather than debugging data that was never actually damaged.
Hit a bug that doesn't match the standard advice?
I diagnose ERPNext and Frappe issues for teams running production instances — the goal is finding the actual root cause, not the first plausible-looking fix. If your error doesn't resolve with the generic steps, tell me what you've already tried and I'll take a look. See the full troubleshooting guide for the common cases first.
Frequently asked questions
Why doesn't the standard ERPNext fix always work?
Because error messages describe a symptom, not a cause, and the same symptom can come from genuinely different failures. frappe.boot is undefined is caused by stale cache most of the time — but a missing System Settings field produces the identical error and needs a completely different fix. Generic troubleshooting guides, including our own pillar, correctly cover the common cause first; these five cases are documented because they're the ones where that common cause is wrong.
Where do these bugs actually come from?
Each one is sourced from a real, public GitHub Issue on the frappe/erpnext or frappe/frappe repositories, or a thread on the official Frappe community forum (discuss.frappe.io). I verified the exact error text and fix against the source thread before writing this — nothing here is inferred or guessed.
Should I try the generic fix first, or jump to these?
Always try the generic fix first — it resolves the error in the large majority of cases, which is exactly why it's the default advice. These five are specifically the cases where you've already tried the standard fix, it didn't hold, and you need the deeper cause.
Is it safe to run the SQL insert or git restore commands directly on production?
Take a backup first — bench --site yoursite.com backup — before any database-level fix (the currency insert) or any Git operation that discards local state (git restore yarn.lock). These are targeted, low-risk fixes matched to their specific documented case, but a backup is standard practice before any production change.
Does the timezone scheduler bug affect every ERPNext install?
No — only installs where the MariaDB server timezone differs from the application container's timezone, which is common in Docker deployments where the two aren't explicitly aligned. If your scheduler shows as enabled but scheduled reports and email digests have stopped arriving with no error logged, this is worth checking regardless of how the instance is hosted.
About the author
Manoj is an ERPNext and Frappe implementation consultant at MithTech in Bengaluru. He runs production ERPNext deployments for manufacturing and distribution businesses and diagnoses issues down to the actual root cause rather than the first plausible fix.