Problem Upgrading Collections from MODX 2.x to 3.x

If you upgraded MODX from 2.x to 3.x, the Collections extra may show an empty grid with no child resources. Here is a step-by-step fix.

How to Fix Collections Extra Empty Grid After Upgrading from MODX 2 to MODX 3

The Problem

After upgrading to MODX 3 and updating the Collections extra to version 4.x, the children grid disappears. It might show "This resource doesn't have any children" even if resources exist inside the folder. The MODX error log gets flooded with 42S22 and 1054 Unknown column errors.

The Cause
  1. MODX 3 uses strict PSR-4 namespaces, so the old CollectionContainer class key is no longer recognized by the system.
  2. The old extension_packages loading method from MODX 2 is obsolete and conflicts with the new bootstrap system.
  3. The Collections package updater fails silently during the upgrade, missing several new columns in the modx_collection_templates table.

The Solution

Step 1Update the Class Keys (Namespaces)

Run this SQL query in phpMyAdmin to migrate the old MODX 2 resource types to the new MODX 3 structure.

UPDATE modx_site_content SET class_key = 'Collections\\Model\\CollectionContainer' WHERE class_key = 'CollectionContainer';
UPDATE modx_site_content SET class_key = 'Collections\\Model\\SelectionContainer' WHERE class_key = 'SelectionContainer';
Note: If the query returns "0 rows affected", open your main Blog folder in the MODX Manager, go to Settings, manually change the Resource Type to "CollectionContainer", and save.
Step 2Remove the obsolete Extension Package

MODX 3 no longer uses this table for Collections. Remove the legacy entry to prevent boot conflicts:

DELETE FROM modx_extension_packages WHERE namespace = 'collections';
Step 3Inject the Missing Database Columns

The installer failed to create the new configuration columns required by version 4.x. Run these queries in the SQL tab to manually patch the table structure. Replace modx_ with your custom database prefix if necessary:

ALTER TABLE modx_collection_templates ADD COLUMN search_query_exclude_tvs VARCHAR(255) NOT NULL DEFAULT '';
ALTER TABLE modx_collection_templates ADD COLUMN search_query_exclude_tagger TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE modx_collection_templates ADD COLUMN search_query_title_only TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE modx_collection_templates ADD COLUMN show_quick_create TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE modx_collection_templates ADD COLUMN quick_create_label VARCHAR(255) NOT NULL DEFAULT '';
ALTER TABLE modx_collection_templates ADD COLUMN fred_default_blueprint INT(10) NOT NULL DEFAULT 0;
Step 4Clear the Cache
  1. In the MODX Manager, go to Manage > Clear Cache.
  2. Go to Manage > Refresh URIs.
  3. Open your hosting File Manager, navigate to core/cache/, and delete all its contents.
Refresh your MODX Manager. The Collections grid will now load the database correctly and display all your child resources.

Did this save you time and a headache?

Consider leaving a tip

Thank you!

Need more?

Something custom for your site?

These extras are free to use. But the best solution is the one made for you: if you need a high-end MODX website, a system around your business, hosting, a fix, or an extra written for your own project, tell me what you need and I will build it around you.

Tell me about your project →See what I do