Fix EspoCRM MySQL join and row size errors

Why EspoCRM MySQL errors appear after customization

A list view, report or record save fails with a MySQL error, and it started after someone added custom entities, relationships or text fields. This is the usual pattern for both errors covered on this page. Neither one means EspoCRM is broken. Both come from how the database stores rows and joins tables, and customization pushes a deployment toward those limits faster than a stock installation reaches them. Each new relationship can add a table to a query, and each new text field adds width to the row that the database must store.

The two symptoms have different causes. A too many joined tables error appears when a query that EspoCRM builds to show related fields, filter across links or feed a report needs more joins than the database engine allows in one statement. A row size too large error appears when the combined storage needed for one row's columns exceeds what the table format permits, which is common when many fields use large text types. Your first step is to capture the exact error text and the statement or screen that triggered it, because the fix depends on which limit you hit.

The numeric limits depend on your database engine and version, so do not assume a figure from a forum post or an older release. The EspoCRM server configuration docs list MySQL 8.0 or newer and MariaDB 10.6 or newer as supported engines. Confirm the join and row size limits, and any storage format defaults that affect row size, in the vendor documentation for the exact version you run, and record that version alongside your EspoCRM version before you change anything. The EspoCRM server configuration docs list the supported combinations.

Telling the join limit error apart from the row size error

The join limit error appears when a single SQL statement references more tables than MySQL allows in one join, which is 61 tables. EspoCRM builds its list views, filters, sorting and reports from joins across entity tables and relationship tables, so the error usually appears when a user opens a list view with many columns, applies a filter across several linked entities, or runs a report that follows many relations. It is typically reported as a SQL error from the list or report request, not on save.

What makes it more likely in EspoCRM is the number of relationships and link fields that a single query has to traverse. Heavily customized instances often add link fields, select-from-related filters and report columns that each pull in another table, and the total can cross the limit even when each individual change looks small.

Where it surfaces: list views with many link-based columns, advanced filters across several related entities, and Advanced Pack reports that reference many relations.
Capture the error text: note the full SQL error code and message, the entity, the list view, filter or report that triggered it, and the exact user action.
Map the relationships: list every link and relationship field in the entity definitions involved, including those added through custom fields and extensions.
Reproduce with the smallest case: identify whether the failure depends on one column, one filter or one report, before removing anything.
Confirm the current MySQL or MariaDB version and sql_mode: check the version against the server configuration requirements before deciding on a fix.

Before changing anything, check which query fails, because the fix is to narrow that query rather than to alter the schema.

Fix options and when each one fits

This table compares the main ways to clear MySQL join and row size errors in a heavily customized EspoCRM, from trimming list views to changing the database setup. Read each row for its data model trade-off, its effect on users, and the upgrade and extension work it creates. Most teams combine two or three options, and the vendor documentation and their own test results should decide the final order.

Fix option	Trade-off in data model and user experience	Upgrade and extension impact	When it fits
Reduce fields or relationships in list views and reports	Smaller list and report queries, but users lose columns they may rely on and must open records to see detail.	Low. Layout changes are usually kept in custom metadata, so review them after each upgrade.	Join errors appear in list views or reports that pull many related fields that are rarely read.
Move rarely used text into a related entity	Long notes or history move out of the main row, which keeps the core record small but adds a click and a relationship to maintain.	Medium. Custom entities and link definitions must be checked against upgrade notes and any extensions that reference the old field.	Several text fields hold long content that is read only occasionally, such as legacy notes or imported comments.
Store large text in file storage or attachments	Content stays out of the database row entirely, but search and filtering on that content stop working unless you plan for it.	Medium. Attachment handling, retention rules and backups must cover the new storage path.	Text is archival, such as scanned notes, email bodies or documents, and users do not filter by it.
Change field types or lengths where data allows	Narrower types can reduce row size, but data that does not fit will be truncated or rejected, so validation and cleanup come first.	Medium. Schema changes are applied through rebuild steps, so take a backup and test on a copy before production.	Fields are oversized for their real content and you have confirmed the maximum values in your data.
Split a heavy entity into two related entities	Each record is narrower and easier to query, but users must navigate between records and reports need to join across them.	High. Entity design, layouts, workflows, formulas and API integrations may all reference the original entity.	One entity has accumulated many unrelated groups of fields over time and the groups have clear, separate owners.
Review database version and engine settings	Can relieve limits tied to the database setup, but does not remove the need for a sound data model.	Medium. Database version changes must match the PHP and database versions listed in the EspoCRM server configuration docs.	You have checked the vendor documentation and your own test results show the server setup is the constraint.

Fixing EspoCRM MySQL errors step by step

This sequence takes a failing list view, report or save from reproduction to a documented, tested fix that keeps the least invasive change and leaves a record for future upgrades.

Back up the database and files first
Before touching anything, take a full database dump and a copy of the EspoCRM application files, including custom entity definitions, layouts and extensions. Your database administrator or platform owner runs the backup, and the change ticket records where the backup is stored and that it can be read back. Done means you have restored the backup into a scratch environment at least once or have a documented, tested restore path, which is covered in the EspoCRM backup and restore topic in this content group.
Reproduce the error in a non-production copy
Restore the backup to a non-production instance that runs the same EspoCRM version, PHP version and MySQL or MariaDB version as production. Open the failing list view, run the failing report or save the failing record, and capture the exact error text and the query that triggers it from the logs. Done means the same error appears on demand in the copy. If it does not reproduce, the cause is likely a difference in version or data, so compare those before continuing.
Inventory entities, layouts and text fields
Export a list of the entities involved, their relationships, the layouts that show related panels, and every text, varchar and multi-enum field on the affected entities. Note which custom fields were added through the Entity Manager and which came from extensions. Done means you have a written inventory showing the count of joined relationships on the failing view and the count and type of text columns on the failing table, which is the evidence you need for the next step.
Identify what the failing query needs
Compare the failing query with the inventory and decide which fields, relationships or select columns the view actually displays and filters on. Separate what the users need on screen from what was added by default. Done means you can name each joined table and each large column the query touches, and mark which ones are required for the business process and which are not used.
Apply the least invasive fix
Choose the smallest change that clears the error: remove an unused relationship from the list layout or panel, narrow the selected fields, move a rarely used text field to a detail-only view, or convert a long text field to a related entity where the design allows it. Avoid broad changes that alter many entities at once. Make the change in the non-production copy first. Done means the change is saved in the copy and the query error no longer appears in the logs.
Rebuild and re-test list views, reports and saves
Run the rebuild steps covered in the EspoCRM rebuild topic in this content group, then test the affected list views, the report, and create and edit saves for a representative record. Include a user with restricted roles, since permissions can change which fields load. Done means every affected view loads without an SQL error, the report returns results, and records save with no error in the application log. Repeat the test on production after the same change is approved.
Document the change for future upgrades
Record the failing view, the query error, the inventory, the chosen fix and the test results in your change log, and note which customizations depend on the change. Store the entity definition and layout files in version control if your team uses it. Done means someone who was not part of the work can find the reason for the change, and the upgrade checklist for the next EspoCRM version lists the affected layouts and fields for retesting.

Risks when you change fields or relationships to fix the error

Fixing a join limit or row size error usually means removing, merging or converting fields and relationships, which touches data, screens, automation and access at once. The cards below cover the risks that tend to surface after such a change, with a check to run before the change and another to run after it.

Data loss during text conversion

Converting a varchar or text field to another type, or shortening a field's length, can truncate existing values without an obvious error. Before the change, export the affected entity to CSV and record row counts and the longest values in each field. After the change, compare counts and sample records against the export, and confirm that no field now holds clipped content. Keep the original column until the comparison passes.

Broken layouts and dynamic logic

Removing a field can leave orphaned references in detail and list layouts, panels, dynamic logic conditions and formula scripts. A missing field may fail silently in a formula and produce empty results rather than an error. Before the change, list every layout, dynamic logic rule and formula that reads the field. After the change, open each record view and edit view for the affected entities as a non-admin user and confirm that fields still display and conditions still fire.

Extensions and custom code that expect removed fields

Custom PHP hooks, API integrations, workflows and installed extensions may read or write the field you intend to remove or merge. These dependencies are easy to miss because they do not appear in the Entity Manager. Before the change, search the custom code directory and workflow definitions for the field name and ask each extension vendor whether it references the field. After the change, run a test record through each integration and check the outbound payload.

Performance shifts after rebuild

A rebuild on a large table can take a long time, lock the table while it runs and change query plans once the column layout changes. Index definitions that depended on the old field may also need to be recreated. Before the change, take a verified backup and schedule the rebuild in a maintenance window. After the change, time the default list view and the most-used reports, and compare them with the baseline you recorded before the work.

Upgrade conflicts with custom entity metadata

Custom entity definitions, field overrides and manual edits to metadata files can conflict with the field structure of a later EspoCRM release. A change that works on the current version may need rework during an upgrade. Before the change, record every custom metadata file you edited and keep the changes in version control. After the change, run the upgrade on a staging copy and check the metadata diff before it reaches production.

Access changes when relationships move

Moving a relationship from one entity to another can change which users see which records once team and ownership fields are recalculated. Records may become visible to a wider group, or disappear from the users who depended on them. Before the change, document the current visibility for each role and team using a test user per role. After the change, log in as those test users and confirm that they see the same records, with no additional access and no gaps.

What to confirm in your database version and EspoCRM release

Whether you hit a 61-table join limit or a row size too large error depends on the database engine and version you run, and on the EspoCRM release that generates the queries. Before changing any field, layout or relation, record your exact MySQL or MariaDB version, your EspoCRM version and your PHP version. EspoCRM's server configuration documentation lists MySQL 8.0 or newer and MariaDB 10.6 or newer as supported database versions, so confirm which engine and version your instance actually uses, not what it was installed with. The EspoCRM 10.0 series is the current major line: 10.0.0 was released on July 2, 2026, and 10.0.10 on October 14, 2026, according to the EspoCRM releases page. If you run an earlier release, check whether your version is still in the series your team plans to stay on.

Next, read the release notes for every version between your current release and your target release on the EspoCRM releases page, and search the project issue tracker for your exact error text and entity names. Look for reports that match your schema, especially entities with many relationships or many text fields. A fix in a newer release may remove the need for a schema workaround, so check this before you redesign anything. Also confirm which extensions you have installed, because extensions can add their own relationships and columns that count against the same limits.

Finally, ask your database administrator to confirm the storage engine, character set and collation of the affected tables, and the row format the server uses. Text columns and multi-byte character sets change how much space each row needs, so a table that looks small can still exceed the row size limit. Ask them to confirm the current innodb_strict_mode setting and whether the instance has been through a hard rebuild, since a rebuild can change column definitions. Write these results down with the version numbers. If the answers are unclear, resolve them in a test copy first, because a schema change made on a production database is hard to reverse.

Limits to confirm before you commit to a fix

The two errors come from database limits that depend on your database version, your schema and your EspoCRM release. The cards below list the points this page cannot settle for you, and who can confirm each one before you choose a fix.

Join and row size thresholds per version

The exact join and row size thresholds differ by database version and storage engine, and the numbers should come from the vendor documentation for the MySQL or MariaDB version you run, not from this page. Record the server version, the engine used by your EspoCRM tables and the error text you see. Then test the fix against that exact version in a staging copy before you apply it to production.

Query changes in each release

Confirm whether the EspoCRM release you run changes the queries it generates for list views, reports or relationship joins. The release notes for your exact version are the place to check, because a patch that alters joins can change which fix still works. Read the notes for every release between your current version and your target before you plan a fix that depends on a specific query shape.

Extension relationships and joins

Installed extensions can add entities, relationships and fields that count toward the join limit, and this page cannot tell you how many an extension adds. Ask the extension publisher which relationships and computed fields it creates, and list them in your environment. Then count the tables a slow list view or report actually joins, so you know whether the extension or your own customizations are responsible.

Hosting platform database limits

Managed database services and hosting panels can impose their own limits on connections, table counts, row sizes or configuration changes that do not apply to a database you run yourself. Confirm these limits with your hosting provider, since a fix that changes table or column layout may be blocked or behave differently on a managed instance. Ask whether you can set the server options your fix needs before you plan the work.

Whether a fix survives a database upgrade

A layout or column change that works on one database version does not automatically hold after a major database upgrade, because limits and defaults can change between versions. Plan a repeat test on the target database version before any upgrade, and keep the rollback steps and a current backup ready. Your own test environment is the only place where this result can be verified for your schema.

Current supported database versions

EspoCRM's supported database versions change with releases, so the versions in your plan should match the current server requirements. Check the EspoCRM server configuration docs for the MySQL or MariaDB versions your target release supports, and confirm your database meets that list before you change a schema. Record the result in your change ticket so reviewers can see which version the fix was tested against.

Questions teams ask about fixing MySQL join and row size errors

What drives the effort to fix EspoCRM join limit and row size errors?

The effort depends mainly on how many custom entities, relationships and fields your instance has, and how many of them feed list views, reports and workflows. Each custom relationship that adds a join to a common query, and each text field that adds to the row width, changes the size of the fix. Installed extensions add their own entities and fields, so they count too. Test coverage matters as much as the schema work, because every change to a list view or a report needs to be checked against real data. Ask for a written scope that lists the entities, relationships and extensions in question, the affected views and reports, and the test cases that will confirm each one works.

Can our own team fix these MySQL errors without a partner?

Yes, many teams do, provided someone understands both the database and the EspoCRM metadata. The work involves reviewing entity definitions, deciding which relationships can be restructured, changing field types with a rebuild, and confirming the result in the UI. Internal teams often underestimate the time needed to trace which views and reports trigger each query, and how custom code depends on the current structure. A partner is most useful when the instance is heavily customized, when the team lacks EspoCRM development experience, or when the change must be completed within a fixed window.

What do we need to provide before the work starts?

The team needs read access to the database schema and the EspoCRM custom metadata, a recent copy of the production database for testing, and a staging environment that matches production's PHP and MariaDB or MySQL versions. You also need change windows agreed with business users, and someone who knows the customizations, including formulas, layouts, hooks and extensions. Confirm backup and rollback procedures before any change. Ask the provider to state these requirements in the written scope so that access and environment gaps are found early.

Is it safe to change field types on production data?

It can be safe when it is planned, tested on a copy of production and backed up first. Changing a text field to a different type or length can truncate or convert data, so you should inspect the longest and most unusual values before changing anything. Run the rebuild in staging, compare record counts and sample values, and keep a verified backup you can restore. Schedule the change in a window when no imports, workflows or scheduled jobs are writing to the affected entity. Ask any provider to describe its rollback steps and how it will confirm the data after the change.

How does this fix affect future EspoCRM upgrades?

Schema changes made to work around these errors can interact with upgrades, because a new release may add fields, indexes or relationships that increase the same limits. Record every custom change in a documented form, including the reason and the entities affected, so that the next upgrade can be tested against it. Review the upgrade notes for each target version and rerun your join and row size checks on staging before upgrading production. Plan upgrades around your extensions and customizations, and confirm the supported PHP and database versions for the target release in the official documentation.

When does a fixed-scope engagement make more sense than internal work?

A fixed-scope engagement suits a defined set of problems, such as a known list of failing views and reports, a bounded number of entities, and a clear acceptance test. It gives you a written scope, deliverables and timeline before work starts, which helps when internal staff are committed elsewhere or when the change needs independent verification. Internal work suits ongoing, small adjustments that your team already understands well. If the root cause involves many interacting customizations or unclear ownership, begin with a short assessment to define the scope, then decide which part to keep in-house.

How DeployOpen scopes and fixes EspoCRM database errors

DeployOpen approaches these MySQL errors as a fixed-scope piece of work on your own EspoCRM instance. We start by reproducing the failing list views, reports and saves, then decide with you whether the fix is metadata, layout, field design or database configuration, and document the change before anything is altered in production.

How we scope

We list the failing views, reports and save operations and the exact error text each one produces.
We inventory custom entities, relationships and text fields that feed the joins or row width.
The written scope names the environments, backup steps and acceptance checks agreed before work starts.

How we build

We reduce unnecessary joins or text fields in entity definitions, layouts and reports where the business need allows it.
We test changes in a staging copy of your instance, with a rebuild and the failing queries rerun.
We confirm database settings against your MariaDB or MySQL version rather than applying generic values.

How we hand over

You receive a record of every metadata, layout and database change, with the reason for each.
We document the reproduction steps and the checks that confirm each error no longer occurs.
Your team gets a walkthrough of how to spot the same limits early when new fields or reports are added.

How we support

Engagements are fixed-scope, and ongoing support, upgrades and testing are available as a retainer.
Retainer work can cover re-checking reports and list views after new customizations or EspoCRM upgrades.
Ask us to confirm in the quote which support hours, response expectations and change windows apply.

Fixing EspoCRM MySQL errors: join and row size limits