Why ERPNext reports time out and when to act
When a General Ledger or stock balance report times out, the first decision is whether the problem is the data, the query or the configuration, because each points to a different fix. Report time-outs usually grow with the number of ledger entries, stock ledger rows and company or warehouse filters a report must scan, not from one broken setting. A finance or operations lead who sees the report work on a small date range but fail on a full fiscal year is seeing a volume and query shape problem. Before changing anything, confirm which report, which filters and which site are affected, and whether the failure happens in the browser or in a background job. Your own team can usually answer those questions from the Error Log and the server logs.
Bring in outside help when the cause spans several layers at once: database buffer sizing, missing indexes on large tables, report permissions that force broad queries, stock closing practices that were never set up, and a web worker timeout that hides the real query time. Those are the points where a change in one layer can hide a problem in another. A partner should also be asked to explain what it will measure before and after each change, and which changes it recommends you make without a further review. Ask for the written scope, the environment where testing happens and the rollback steps before the work starts.
DeployOpen works inside your own infrastructure, including your cloud accounts, data centers or air-gapped networks, so report data, database dumps and logs stay under your control during diagnosis and tuning. ERPNext is free and open source under the GPL-3.0 license, and the Frappe Framework it runs on is licensed under MIT, so your team keeps the right to run and change the software without a license fee. Confirm the versions in your environment against the Frappe supported versions page before planning any change, because support windows affect which fixes you can apply.
Which fix fits which report problem
This table matches each slow or timing-out report symptom to the fix that targets it, what that fix changes and its trade-offs. Confirm each option against the ERPNext version you run before you change anything, because report behavior, settings and screens differ between major versions.
| Fix | Symptom it targets | What it changes | Trade-offs |
|---|---|---|---|
| Prepared report | General Ledger or stock report times out in the browser on large date ranges or many rows | Runs the report in a background job and stores the result for the user to download or view later | Results are a snapshot, so they can be stale; confirm the report supports it in your version |
| Report and user permission tuning | Report is slow only for some users, often those with many role or user permission restrictions | Simplifies role and user permission rules that filter report rows, reducing per-row checks | Less granular access control; any loosening must be reviewed by your access owners |
| Stock closing entry | Stock Balance or Stock Ledger reports slow down because the transaction history keeps growing | Summarizes stock movements up to a closing date so reports scan less history for later periods | Requires a deliberate closing process and review; corrections after closing need a planned procedure |
| Database indexes | Specific filtered or sorted queries are slow across many records, visible in the database slow query log | Adds or uses indexes on the columns the query filters and sorts on | Indexes add write overhead and disk use; changes to core tables need a tested change plan and may not be supported by ERPNext updates |
| Report filter and date range narrowing | Report fails because it asks for too many rows at once | Limits the period, company, warehouse or item scope in the filters | Users may need several runs to see the full picture; reporting standards must reflect this |
| Database and server capacity review | Reports slow across all users at peak times rather than one report | Adjusts database memory and worker capacity so concurrent work has room | Hardware or hosting cost; should follow measurement, not precede it |
Diagnosing and fixing a timing-out report step by step
This sequence moves from a reproducible timeout to a measured fix, so the team changes one thing at a time and can show that the report now completes. Each step ends with a check that tells the next step whether it is needed.
Reproduce the timeout with a fixed filter range
Ask the user who reports the problem for the exact report name, company, filters and date range that fail, then run the same report on a staging copy of the site with those values. Record the company, the period, the account or item filters, and whether the timeout happens in the browser or in a background job. The step is done when the failure repeats with the same inputs. If it only fails for one user, note that and move on with that user's roles in mind.
Check the Error Log and worker logs
Open the Error Log in the desk and filter it to the time of the failed run, then read the server log and the worker error log for the same minute on the bench. Look for the request path, the SQL error or the worker timeout message, and note whether the report was killed at the web layer or in a queue. The step is done when you can say whether the failure is a request timeout, a worker timeout or an application exception. Do not change settings until this classification is written down.
Confirm whether the report is a prepared report candidate
Check whether the report supports prepared report mode in its settings and whether the failing request is a synchronous call from the desk. Large General Ledger or stock reports that run in the browser are the usual candidates for background preparation, while reports with a small date range may not need it. Run the report with prepared mode enabled in staging and confirm a Prepared Report record is created and completes. The step is done when the report returns the same totals in prepared mode as in the synchronous run.
Review user and role permissions that add filters
Compare the report output and the generated SQL for a full-access user and for the affected user, because User Permissions and role-based permissions can add conditions that change the query plan. Confirm which company, cost center or warehouse restrictions apply and whether they are applied after the data is fetched. The step is done when both users run the same filter set and you know whether the timeout depends on the permission conditions. If it does, record the permission rule as the input for the index review.
Check stock closing and period close status
Confirm whether the period closing voucher, accounting period closing and stock closing entries for the date range are in the state the team expects, and whether recent stock reposting or backdated entries are still running. Reports that scan a long period without a closing point often do far more work than the same report over a closed period. The step is done when you can state the last closed period, the last stock closing date and whether any reposting job is still queued for the range being tested.
Confirm or add indexes on the filtered columns
Using the SQL captured in the earlier steps, run EXPLAIN in MariaDB on the staging site to find full table scans on the filtered columns, such as posting date, company, account, item and warehouse. Check existing indexes with SHOW INDEX before proposing a new one, and consider whether a composite index matches the filter order the report uses. Test each candidate index in staging, record the change and the rollback statement, and confirm with your database owner before applying it to production. The step is done when the EXPLAIN plan uses the index and the output rows match the baseline.
Re-measure the report on the same inputs
Run the original failing filter set on staging and on production after the change window, then compare the run time, the worker or request outcome and the totals with the baseline from step one. Repeat the run for the same user to confirm the permission path behaves the same. The step is done when the report completes within the request limits, the totals match the pre-change result, and the Error Log shows no new entries for the run. Keep the before and after evidence with the change record.
Security and operational risks when tuning reports
Speeding up a slow General Ledger or stock report usually means changing who can run it, where its output lands, or how the database is structured. Each of those changes can expose financial data or slow the system down in ways that are harder to see than the original timeout. The cards below name the risk and the control an operations team can review before and after each change.
Widening report permissions to speed up
A report that fails for a user with limited roles is sometimes fixed by granting broader report or DocType access, which removes the symptom but also exposes ledger data to people who should not see it. Review each role that gains access to a report, and confirm that User Permissions and company restrictions still filter the rows returned. Record who approved the change and test the report as a restricted user, not only as Administrator.
Financial data in prepared report files
Prepared reports store their generated output as files, and those files can contain full ledger or stock valuation detail. Confirm where the files are kept, who can download them from the desk, and whether they are private or public. Set a retention approach for generated output and include those files in your backup and access review, since a prepared report can outlive the permission that created it.
Schema changes without a verified backup
Adding indexes, dropping stale columns or rebuilding tables changes the database that ERPNext depends on, and a failed change can leave a site in a state that is hard to recover. Take a full backup of the site, confirm it restores in a test environment, and record the Frappe and ERPNext versions before the change. Run the change first on a copy of production data, not on the live site.
Index changes that slow writes
Every extra index makes inserts and updates on the same table do more work, and General Ledger Entry and Stock Ledger Entry tables receive constant writes during day-to-day posting. An index that speeds one report can slow saves, submissions and background reposts elsewhere. Measure write latency and posting time before and after the change, and keep a documented rollback statement for each index added.
Stock closing changes that alter valuation
Changing stock closing or period settings to make a report faster can shift the balances that reports read from, which affects valuation and the figures finance has already reviewed. Confirm with the finance owner which closing entries are final before touching them. Compare report totals before and after the change for a fixed date range and keep the comparison as audit evidence.
Change records and review trail
Report tuning often spreads across permissions, scheduler settings, database configuration and custom scripts, and no single person may remember every step. Keep a written change record for each tuning action, including the affected site, the user roles checked and the test results. Review the record with the finance and security owners before the change goes into production, and keep it with your other operations evidence.
Questions buyers ask before fixing report performance
What drives the cost and effort of a performance review for slow ERPNext reports?
The main drivers are the number of slow reports, how much General Ledger and stock history each one scans, how many sites and companies share the database, and whether a staging copy of production already exists. A review that covers only the General Ledger and one stock report is much smaller than one that covers every report users complain about across several companies. Cost has three parts: the consultant time to reproduce and profile the reports, the change work (indexes, report settings, closing practices or code changes), and the retest. Ask for a quote that lists each report, the environment it will be tested in, and what is delivered at the end. Hosting costs are separate. The ERPNext pricing page lists the Frappe Cloud shared site and server prices, and self-hosting ERPNext is listed there as free.
How long does diagnosing slow ERPNext reports usually take?
Duration depends mainly on data volume, the ERPNext version in use, and how many reports are in scope. A site with a few years of ledger and stock entries takes longer to profile than a young site, because each query touches more rows and more of the database. The version matters because supported releases differ in how reports and background jobs are handled. Frappe's supported versions page lists version 15 as supported until the end of 2027 and version 16 until the end of 2029, so you should confirm which version your site runs before planning. No fixed duration applies to every site, so ask the provider for a timeline based on your report list and a copy of your data. Fixed-scope engagements agree the timeline in writing before work starts.
What does our team need to provide for a performance review?
The review needs four things. First, administrator or read access to the affected sites, or a named contact who can run the reports for us while we observe. Second, a staging copy of the production database and files, refreshed recently enough that the data volumes match what users see. Third, a written list of the slow reports and time-outs, with filters users typically apply, the company and date ranges involved, and how often each report runs. Fourth, server and application logs for the affected period, including the web and worker logs and the Error Log and Scheduled Job Log entries from the desk. Also confirm whether scheduled reports or prepared report jobs already run, and share any custom reports or scripts. Personal data in the copy should be handled under your own data protection rules, and the provider should agree how staging data is stored and deleted.
Can our internal team fix slow ERPNext reports without outside help?
Yes, many teams can, particularly when the problem is a single report and the team already administers ERPNext with bench. Typical internal work includes enabling prepared reports for heavy reports, reviewing role and user permissions that add filters to queries, scheduling stock closing entries, and checking that database indexes and MariaDB settings are in place. The work becomes harder when the cause is in custom reports, custom scripts, or query logic inside an app, because the team then needs to profile SQL and change code safely. A useful test is whether your team can reproduce the slow report on a staging copy, read the query plan, and verify the fix against the same data. If not, an outside review can cover the reproduction and diagnosis, and your team keeps the changes and runbook afterward.
How are fixes scoped under a fixed-scope written agreement?
Under a fixed-scope agreement, the report list, environments, deliverables and acceptance checks are written down before work starts. A typical scope names each report, the fix category (for example prepared report, permission change, stock closing practice, index or custom code change), the staging test, and the handover material. Changes that would alter business logic, such as how valuation or ledger postings work, should be listed as separate decisions for your finance or operations owners. Anything found outside the agreed list is raised as a change request with its own written estimate. Ask that the agreement states how the fixes are deployed to production, who approves it, and what rollback steps exist. Ongoing monitoring, upgrades and continuous testing are available as retainers, so recurring work can be agreed separately from the initial review.
What risks come with changing indexes or report settings on a live ERPNext?
Index changes and report setting changes can lock tables, slow writes during the change, or alter query plans in ways that affect other reports. Adding an index to a large ledger table can take time and needs a maintenance window on busy sites. Prepared reports move work to background jobs, so the worker queues must have capacity or reports will wait. Stock closing and reposting changes affect historical valuation, so they need finance sign-off. The safe path is to test each change on a staging copy with production-like volumes, record before and after timings for each report, take a backup before production changes, and define a rollback step. Ask the provider to show how they measure results and which reports they will re-run after each change.
Do the fixes require a version upgrade or a new hosting plan?
Not necessarily. Many report time-outs come from settings, permissions, data practices and indexes, which can be handled on the version you already run. An upgrade is a separate project, and the supported versions page should be checked first, because version 14 reached end of life on January 31, 2026. Hosting changes, such as more memory, a dedicated database server or a read replica, are decided after the diagnosis shows where the time is spent. Frappe Cloud prices for shared sites and dedicated servers are listed on the ERPNext pricing page, and self-hosted ERPNext has no license fee there. Ask for the diagnosis first, then decide on hosting with the figures in hand.
Limits to confirm in your environment
Most report fixes depend on four things: the ERPNext version you run, what your hosting tier lets you change, how that version's reports behave, and whether your database accepts index work. Confirm each one before you commit to a plan, because a fix that works on a self-managed bench may be blocked on a shared or managed host.
Supported version and end-of-life dates
Confirm which ERPNext and Frappe Framework version your site runs and whether it is still inside its support window. Version 14 reached end of life on January 31, 2026, so a site on that line needs an upgrade plan before any tuning work pays off. Check the supported versions page for the dates that apply to your release, and plan report fixes on a version that will still receive patches.
Hosting tier and allowed changes
Confirm whether your hosting plan lets you change site configuration, install custom apps, add database indexes, or enable server-side scripting. Shared public benches on Frappe Cloud do not allow Server Scripts, so a scripted report workaround will not run there. Ask your provider in writing which of these changes they support before scoping the work.
Report behavior in your version
Confirm how the General Ledger and stock reports in your version handle prepared reports, filters and background execution. Behavior changes between minor releases, so test the exact report, filter set and date range that times out, not a generic sample. Record the version number with each test so results stay comparable after updates.
Index changes on your managed database
Confirm whether your managed MariaDB service allows custom indexes on Frappe tables and whether schema changes must go through the provider. Some managed offerings restrict DDL, limit maintenance windows, or require a support request. Ask how index creation is rolled out, how long it can lock tables on your data volume, and how it is reverted if a query plan gets worse.
Background job and permission constraints
Confirm whether your environment runs prepared reports on the long queue and whether your roles can run them without broader desk access. A report that queues but never finishes often points to worker capacity or permission settings rather than the query itself. Check worker counts and report permissions together, so a fix does not expose data to users who should not see it.
What a performance engagement produces
A performance engagement on slow ERPNext reports produces four deliverables, and the first is a timed baseline for each report in scope. For General Ledger, stock balance, stock ledger and any other report that times out, the baseline records the filters used, the site and bench version, the user role that ran it, the time to first result and whether the report ran synchronously or as a prepared report. Without that baseline, no later change can be judged. Each report is timed on the production-like copy, so the numbers describe the environment the operations team actually runs.
The second deliverable is a written change list with rollback steps. Every proposed item is named precisely: a database index addition, a site_config or MariaDB setting, a change to report permissions or role assignments, a stock closing entry or repost approach, or a prepared report setting. Each item states what it changes, which reports it is expected to affect, who approves it, and how to reverse it. The third deliverable is the tested change set itself. Index and configuration changes are applied in staging, re-timed against the baseline, and checked for side effects on posting and reposting before anything is recommended for production. Results are reported as measured, including changes that did not help.
The fourth deliverable is runbook notes for the operations team, covering how to rerun the timed checks, which logs to watch when a report fails, how prepared report jobs are queued and cleared, and which changes must be repeated after an ERPNext or Frappe upgrade. Scope is agreed in writing before work starts, so the exact reports, sites and environments are fixed up front. The engagement does not promise a particular speed gain, because the result depends on data volume, hardware and posting history. Confirm with the partner which environments are included, who runs the production change window, and how retesting after a minor release is handled.
How DeployOpen scopes and supports report performance work
DeployOpen approaches slow ERPNext reports as a scoped piece of work on your own infrastructure, starting with the reports that time out and the data behind them. We plan the changes in writing, build and test them against a copy of your data, and hand over the settings and runbooks your team needs to keep the reports fast.
How we scope
- Inventory the General Ledger, stock and other reports that time out, with the users, filters and date ranges that trigger them.
- Confirm the ERPNext and Frappe Framework versions in use and whether the site runs on Frappe Cloud or your own infrastructure.
- Agree in writing which changes are in scope, such as prepared reports, permission review, stock closing entries or indexes, before work starts.
How we build
- Measure baseline report run times and database load on a staging copy of the production site before changing anything.
- Apply one change at a time, such as enabling prepared reports or adjusting report permissions, and record the effect on each report.
- Test results against reconciled totals so that faster reports still show the same General Ledger and stock balances.
How we hand over
- Document each configuration change, the reasons for it and how to reverse it, with the report names and filters it affects.
- Walk through the runbook with the administrators who will run month-end and stock close, including what to do when a report still times out.
- Leave a list of follow-up items, such as database tuning or a read replica, with the evidence that would justify each one.
How we support
- Engagements are fixed-scope, so the agreed deliverables and timelines are confirmed in writing before work begins.
- Ongoing support, upgrades and performance reviews after each ERPNext release are available as a retainer.
- Ask any partner to confirm how they will reconcile report totals, what access they need to your environment and who signs off each change.
