When to clear EspoCRM cache and when to run a rebuild
Start with the symptom. If a running EspoCRM instance shows stale layouts, missing fields or old metadata after you changed the Entity Manager, a layout or a field definition, the first step is usually to clear the cache, not to rebuild. Clearing the cache discards cached metadata and compiled files so the application reads your latest configuration. An upgrade step that asks for a rebuild points to a different layer: the database structure that EspoCRM generates from entity definitions. A standard rebuild reconciles those definitions with the database, which is what you need after adding entities, fields or indexes. A hard rebuild goes further and works on the columns themselves, including their types and collations, so it is the option that changes existing database structure and needs the most care.
Map the symptom to the layer before you act. Stale screens, labels or dynamic logic that persist after a save generally sit in cached metadata and code, so clearing the cache is the lowest-impact fix. New fields that do not save, missing columns or filters that fail with database errors point to the generated structure, which calls for a rebuild. Character set or sorting problems, such as text that compares unexpectedly after a migration, point to columns and collations, which is the only case that justifies a hard rebuild. Do not run a hard rebuild to fix a display problem. Confirm which of these steps your installed version offers, the menu path in the administration panel, and whether the CLI equivalent exists, in the EspoCRM documentation for that exact version, because commands and menu paths change between releases.
Before you run any rebuild on a production instance, take a full backup of the database and the files, and confirm you can restore it. Schedule the work in a maintenance window, since rebuilds can lock tables and users may see errors while they run. Record the symptom, the version and the change that triggered the step so you can tell whether the fix worked. If the first step does not resolve the issue, escalate one layer at a time instead of jumping to a hard rebuild. Ask your implementation partner to confirm, in writing, which layer your change touches and the exact sequence for your version.
Rebuild options and when each fits
This table compares clear cache, the admin panel rebuild, the command-line rebuild, hard rebuild and the backup you take before any of them, across what each acts on, who can run it and when it fits. Start with the lightest step that addresses the symptom and move down only when needed. The main takeaway is that anything that touches database structure or collations needs a verified backup and a check of the docs for your version first.
| Option | What it acts on | Who can run it | When it fits and what to confirm |
|---|---|---|---|
| Clear cache | Cached metadata, layouts and other stored application data | Administrator in the admin panel, or the server user from the command line | Use after a layout or metadata change does not show. Confirm which cache items your version clears. |
| Rebuild from admin panel | Application metadata, database schema and cache, regenerated from current definitions | Administrator with the admin role | Use after adding or changing custom entities, fields or layouts. Confirm how the run behaves for logged-in users on your version and check the application log afterward. |
| Rebuild from command line | The same rebuild work as the admin panel, run as a process on the server | Someone with shell access, running as the web server user | Use when the admin panel times out or is unreachable. Confirm the exact command and file ownership for your install before running it. |
| Hard rebuild | Database columns and collations, which can change table structure | Administrator with server access, after a verified backup | Use only when column or collation drift is suspected. Confirm in the docs for your version whether it runs from the UI, the command line or both, and how it handles large tables. |
| Backup before running | Database contents and application files | Administrator or database owner | Required before a hard rebuild and advisable before any rebuild that changes schema. Confirm the backup method and test a restore on a copy before relying on it. |
How to run an EspoCRM rebuild safely in sequence
This sequence gives you a rebuild that is recoverable at every step, so you can confirm the symptom is fixed, see exactly what changed and stop before any destructive change if something looks wrong.
Confirm the symptom and scope
Before touching the instance, write down the exact symptom, such as a field missing from a layout, a list view that errors, or a formula that no longer evaluates. Note which entities, users and environments are affected and whether the problem started after a metadata change, an extension install or an upgrade. Reproduce it once in the browser and record the URL and the time. The step is done when you can describe the symptom in one sentence that another engineer could reproduce, and you know whether a rebuild is the right tool at all, since many layout or permission problems have narrower fixes.
Take and verify a backup
Before any rebuild, take a full backup of the database and the EspoCRM files, including custom entities, layouts and the custom directory. Store it outside the host being changed. Verification matters as much as the backup itself: confirm the dump file is not empty, check its size against the previous backup, and if you can, restore it into a separate test instance and open a known record. The step is done when you have a restorable copy you have actually opened, with its location and timestamp written in the change record. Follow the EspoCRM backup and restore guidance for your deployment type.
Plan a window if users are active
If people are signed in and working, agree a short maintenance window with the sales and service leads and tell them to save their work and avoid bulk actions, imports and mass email during the change. Confirm that no scheduled jobs, workflows or email fetches are running heavy batches, and check the job queue for pending items. Ask who will be contacted if records look wrong afterwards. The step is done when the window is communicated in writing, the queue is quiet, and a named person is available to check results with you.
Clear the cache
Clear the application cache first, using the admin panel cache option or the CLI command for clearing cache. This is the least disruptive action and often resolves stale layouts, labels and metadata without a rebuild. Then reload the affected record and list view in a fresh session. The step is done when the symptom either disappears or stays the same; if it stays, record that result, because it tells you the cause is probably in the database schema or the stored metadata rather than cached content.
Run the rebuild
Run the rebuild from the admin panel or from the command line on the server, using the same method your team documents for this instance. Watch the output for errors and confirm it completes rather than stopping partway. Keep the terminal output or the screen result in the change record. The step is done when the rebuild reports completion without errors and the process has exited, not when it appears to hang or is interrupted.
Check affected entities and list views
Open the entities involved in the symptom and check them one by one: create a test record if your policy allows, open an existing record, edit a field, open the list view with the default filters and sort, and check one related record link. Compare the result with the expected behavior from before the change. The step is done when each affected entity shows the expected fields, layouts and values, and you have written down any entity that still fails.
Review the application log for errors
Open the application log on the server, normally under the data logs location, and filter for the time window of the rebuild and for error and warning levels. Look for database errors, failed SQL, PHP fatal errors and messages that mention the entities you checked. Match any error to the step you just performed. The step is done when the log shows no new errors for the window, or each error has a recorded cause and a decision. Do not restart services until you have captured the relevant lines.
Consider a hard rebuild only after the rest fails
A hard rebuild rebuilds the database structure, including columns and collations, so treat it as a separate change with its own backup and window. Consider it only if the cache clear and standard rebuild did not fix a schema-level problem and the log points to missing or mismatched columns or collation issues. Confirm the backup from step two is still valid, get sign-off from the owner of the instance, and run the hard rebuild with the same checks as before. The step is done when the decision, the reason and the result are recorded, or when you decide not to proceed and document the alternative fix.
What a hard rebuild can change in your database
A hard rebuild asks the database to match the current entity definitions, so it can alter tables that already hold production data. The cards below cover the risks that matter most on a running EspoCRM, and each one names what to rehearse in a copy of the instance before you touch production.
Column and collation changes
A hard rebuild can rewrite column definitions on existing fields, including type, length and collation changes that follow from your entity metadata. Text that sorts or compares differently after a collation change can alter filters, duplicate checks and search results. Before the run, export the current information_schema column definitions for your key entities and compare them with the same export afterward, looking for changed types and collations.
Custom fields that depend on schema
Custom fields and entities you added through the Entity Manager map to database columns and tables that the rebuild reconciles. If a field was renamed, retyped or removed in metadata, the rebuild may drop or move the data it held. In a copy of the instance, pick a custom field with real values, run the rebuild, and confirm the values are still present and correctly typed in list views, detail views and reports.
Locking and downtime on large tables
Schema changes on large tables can take locks that block reads and writes for as long as the change runs, and the duration depends on table size, engine and database version. Users may see errors or stalled screens while this happens. Measure row counts for the largest entities, time the rebuild in a copy of the instance with a production-sized dataset, and schedule the production run in a window where your team can watch it finish.
Partial changes after a failed run
If a hard rebuild fails partway, some tables may be altered while others are not, and the application may not match either the old or the new schema. Recovery depends on having a verified backup taken before the run, not on re-running the command. Rehearse a forced failure in a copy, confirm that your restore procedure returns the database and files to a consistent state, and record how long that restore took.
Extensions and custom code on old structure
Extensions, hooks, formula scripts and custom PHP may reference columns, table names or field types as they existed before the rebuild. A change that is harmless to the core can break a custom list view, a workflow or an integration that reads the database directly. Inventory every extension and custom script that touches your entities, then run their main paths in a copy after the hard rebuild and check the logs for new errors.
Who can run a rebuild on each EspoCRM hosting model
If you installed EspoCRM with the installation script for Ubuntu, Debian or Linux Mint, the stack runs in Docker with Nginx and MariaDB on a host your team controls. Anyone with root or sudo on that host can reach the application container and run maintenance commands there, so the practical question is which named people hold that access and whether the rebuild procedure is written down.
- Shell access: The person who holds SSH access to the host can enter the application container. Confirm the list of named accounts with this access.
- Built-in utility: The script installs a
command.shutility for backups, restores and upgrades. Check the current installation docs for its exact commands before assuming it covers cache or rebuild steps. - Docker group membership: Membership in the Docker group gives effective root control of the host, so treat it as an administrator privilege.
- Web admin panel: Administrators can use admin panel tools with an admin login, but that login is separate from server access and does not grant shell rights.
Before planning a rebuild, record who can run commands on the host, which utility commands your installed version documents, and who approves the change.
On your own servers or a custom Docker Compose setup, the web server, PHP, database and scheduled jobs are often split across hosts or owned by different teams. The rebuild tools run where the EspoCRM application runs, so you need access to that application host and must run commands as the user the web server uses. The server configuration docs list PHP 8.3 to 8.5, MySQL 8.0 or newer, or MariaDB 10.6 or newer or PostgreSQL 15, on Apache, Nginx or IIS.
- Application host access: Commands run from the EspoCRM directory on the application server. Confirm who can reach that server, especially when a platform team manages the virtual machines.
- File ownership: Running CLI commands as root can leave files owned by root, which the web server may then be unable to read or write. Run them as the web server user.
- Database permissions: A rebuild can change database structure. The database team should approve the backup first and confirm the application account can make those changes.
- Container runtime access: In Docker, access goes through the container runtime. Check whether the operations team restricts container exec rights.
- Change window: Ask the owners of the web server, cron and database for a maintenance window that covers the rebuild and a rollback plan.
Confirm in writing which team runs the rebuild, which team owns the backup, and who can approve a restore if something goes wrong.
On a hosted EspoCRM Cloud plan, the provider operates the infrastructure, so server shell access and server-level maintenance are not in your hands. The pricing page lists Basic at 15 US dollars per user per month with a minimum of 3 users, Enterprise at 25 dollars with a minimum of 5 users, and Ultimate at 69 dollars with a minimum of 10 users, and states that the Advanced Pack is included in all cloud plans. Those plan details do not confirm which cache, rebuild or backup controls you receive, so ask the provider directly.
- Shell and CLI: Assume you have no server shell unless the provider confirms otherwise in writing.
- Admin panel tools: Ask whether the admin panel on your plan exposes cache clearing or rebuild actions, and whether any of them are restricted.
- Who triggers a rebuild: Ask whether the provider runs rebuilds on request, how requests are submitted and what notice period applies.
- Backups and restore: Ask what backups are taken, how often, how long they are kept, and whether you can restore on your own or must request it.
- Support path: Ask how to report a stuck or failed state and what details the provider needs to diagnose it.
Get these answers in the order documentation or contract before you rely on any self-service rebuild step.
Why a backup comes before any rebuild, and how to test it
A rebuild can change the database structure, not just the cache, so a backup of both the files and the database must exist and be restorable before you start. A hard rebuild in particular cleans up database columns and collations, and that is the step that can alter data in ways that are hard to reverse. Take the backup on the same day as the work, with the instance in a known state, and record which EspoCRM version and which custom entities, extensions and formula scripts are present so you can match them during a restore. Confirm with your own environment where the backup files are stored and that the storage is separate from the server you are changing.
The EspoCRM installation script deploys a Docker-based stack and includes a command.sh utility for backups, restores and upgrades, which is the simplest starting point if you installed with it. If you run EspoCRM another way, the manual file and database dump steps are covered in the sibling topic on EspoCRM backup and restore. Whichever method you use, confirm that the backup captures the Docker volumes or upload directories that hold attachments, not only the database, because a database-only backup restores records without their files.
Do not treat a job that reported success as proof that the backup is good. Restore the backup to a separate host or a throwaway copy of the stack, then log in, open a few records with attachments, check a custom entity and a workflow, and run a rebuild there first. Restore tests also show whether the PHP and database versions in your target environment match the ones the backup was taken from. Repeat this test on a schedule, and record the date, the backup file and the result so the team knows the last verified restore before anyone runs a rebuild on production.
How to keep rebuilds inside your change control and access model
Rebuilds, hard rebuilds and cache clears change how a running EspoCRM behaves, so they belong inside the same access and change controls as other production work. The four controls below connect who can run them, when they run, where admin access comes from, and how the run is recorded afterward.
Name the people allowed to rebuild
Limit rebuild and cache actions to a short, named list of administrators. The EspoCRM security guidance recommends avoiding admin accounts for daily work, so the people on this list should have a separate admin account they use only for maintenance and a regular user account for everything else. Ask who holds the admin role today, and whether any of those accounts are used for routine record work. Remove admin rights from anyone who does not need them for rebuilds.
Record the window and approver
Before a hard rebuild, agree a change window with the business owner of the CRM, and record who approved it, the start and end time, and the backup that was taken first. A hard rebuild rewrites table structures and collations, so a rebuild during peak sales hours or with users still logged in makes failures harder to diagnose. Keep this record with the change ticket so the next person can see what changed and when.
Restrict admin access by address
Where your deployment supports it, limit admin logins and the administration area to known networks, such as a corporate VPN or a bastion host. The EspoCRM security docs describe restricting access by IP address as a recommended control. Confirm with your web server or firewall team which paths can be restricted without blocking the API or the cron requests your instance depends on, and test that rebuild tools remain reachable from the approved location only.
Log who ran what
Keep a record of each rebuild, cache clear and CLI command, including the operator, the host, the time and the outcome. Compare the EspoCRM application log and your web server access log with the change record after each run, so that an unexpected rebuild can be traced. Confirm where your instance writes logs, how long they are kept, and who can read them, because admin activity logs are only useful if they survive the maintenance window.
Questions teams ask before running an EspoCRM rebuild
Can an EspoCRM rebuild run without downtime?
A standard cache clear and rebuild usually finishes quickly, but users can see errors or stale metadata while it runs, so plan a short window for production. A hard rebuild that alters database columns or collations is different: it changes table structures, so treat it as a maintenance task with users signed out. Confirm the exact behavior for your EspoCRM version in the official documentation and rehearse the step on a staging copy that matches production data volume before deciding on a window. Ask your partner to state in writing which steps need downtime.
How long does a rebuild take, and what drives the duration?
Duration depends on what the rebuild touches, not on a fixed figure. The main drivers are the number of records in affected entities, the number of custom fields and indexes that need reprocessing, the database engine and its configuration (MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15 are the supported options in the server configuration docs), and the hardware the database and PHP processes run on. Cache clears are short; hard rebuilds on large, heavily customized instances take longer. Measure the run on staging and ask any quote to state the assumed record counts, field counts and database version it is based on.
Can an internal admin run the rebuild, or should a partner do it?
An internal admin with database access and a tested restore path can run a standard rebuild from the admin panel or the command line. A partner adds most value when the rebuild is a hard rebuild on a heavily customized instance, when custom entities, formula scripts or extensions may be affected, or when there is no one on the team who has done a database-level change before. Decide based on your team's experience, change control rules and the risk of the instance. DeployOpen can plan, run and document the rebuild as a fixed-scope piece of work, with the change steps written out for your team to repeat later.
What does a partner need from our team before a rebuild?
Expect to provide the following before work starts:
- Access to the EspoCRM instance, its web server and its database, with the rights needed for the chosen method
- A staging copy with recent production data, so the rebuild can be rehearsed
- A verified backup of files and database, plus a tested restore procedure
- A named change window agreed with business users, and a contact who can approve a rollback decision
- A list of recent customizations, extensions and custom fields, so the scope is accurate
Ask the partner to confirm these items in the written scope.
What is a one-time task, and what recurs after a rebuild?
The first hard rebuild after a schema change, a cleanup of columns or collations, and the initial staging rehearsal are one-time work. Cache clears and standard rebuilds recur whenever metadata, layouts, entities or extensions change, and they are usually part of normal change control. Backups, restore tests and monitoring of the rebuild outcome also recur. If you want a partner to run rebuilds in future, ask whether that is covered by a retainer or billed per change, and what response times and reporting are included in the written scope.
What should we do if a rebuild fails midway?
Stop further changes, leave the instance in its current state, and capture the error from the application log and the web server or PHP logs before trying again. Do not run repeated hard rebuilds against production without understanding the failure. If the database structure is partly changed, the recovery path is your tested backup and restore procedure, so confirm that restore works on staging before the rebuild starts. Record the exact step that failed, the EspoCRM version, the database version and the customizations involved, then rehearse the fix on staging. Include a rollback decision point in the written plan.
What should a quote for a rebuild include?
A useful quote lists the scope by method (cache clear, standard rebuild, hard rebuild), the environments covered (staging and production), the backup and restore checks, the rehearsal steps, the change window and rollback plan, and the documentation delivered afterward. It should also state the assumptions behind the work: instance size, number of custom entities and fields, database engine and version, and any extensions that must be checked. Ask which items are fixed and which depend on findings during staging. DeployOpen does not publish a price list, and a quote follows from the written scope.
How DeployOpen scopes and runs EspoCRM rebuilds and maintenance
DeployOpen treats an EspoCRM rebuild, hard rebuild or cache clear as a change to a running system, not a button press. We agree the scope in writing, rehearse the work on a copy of your instance, and hand over a runbook your team can repeat.
How we scope
- Written scope lists the instances, environments and EspoCRM version the rebuild covers, with the owner of each step named.
- We confirm whether the work is a cache clear, a rebuild or a hard rebuild, because each carries a different risk to data and downtime.
- We inventory custom entities, field changes and extensions, since these determine what a rebuild must regenerate and verify.
How we build
- We rehearse the agreed sequence on a restored copy of production, including the backup taken before any change.
- We record the exact commands, the admin panel steps and the CLI invocation for each environment, so the procedure is reproducible.
- We check the database collation, schema and log output after the rebuild and compare record counts with the pre-change baseline.
How we hand over
- You receive a runbook covering backup verification, the rebuild steps, rollback criteria and the post-change checks.
- We document which symptoms call for a cache clear and which call for a rebuild, so operators do not default to the heavier action.
- Your team runs one supervised rebuild with us observing, then carries out later rebuilds on its own with the runbook.
How we support
- Fixed-scope engagements close when the agreed deliverables are accepted, and changes after that are scoped separately.
- Ongoing support, upgrades and continuous testing are available as a retainer if your instance needs regular maintenance windows.
- We ask you to confirm backup retention, change approval rules and the maintenance window with your own change process before work starts.
