Migrating to the New Event Data System

💡 If you are having issues with the migration, please note:

The migration is recommended, but not required. Your events and calendar will continue to work just as they did before the 6.0 update, even if you aren’t able to migrate yet. The migration allows you access to the new features, but an unmigrated site is still fully functional.

Please make sure you have updated to the most recent version of The Events Calendar. Our team is focused on finding and fixing bugs, so it’s possible that an issue you’re facing was fixed in a recent maintenance release.

Be sure to check out the Troubleshooting guide below and our Known Issues page. If you continue to have trouble with migration, please contact our support team and include as much information as possible about what you’re experiencing.

When you update to The Events Calendar 6.0, you’ll immediately be prompted to migrate your site to our new event data storage system. All of the new features and improvements in 6.0 rely on this structure, so you must migrate your site to take advantage of the new features.

How do I migrate my site?

We’ve built a tool to manage the migration process. To get started, go to Events > Settings > Upgrade. From there, follow the instructions to go through the migration preview and then the migration itself. Once the migration is complete, your site will be running on our new system and you’ll be all set.

We strongly recommend that you test the 6.0 plugin updates and the event migration on a staging site. This allows you to identify and address any issues that may come up without impacting your live site. When you’re ready to start the migration on your live site, do a back up of your site as an extra precaution.

👉 More tips for a smooth migration

What happens during migration?

In order to build our new features (and awesome future features!), we’ve completely changed the way that event data is handled. Your existing events are in the old system. You can think of migration as replacing the crumbling foundation under a house. We have to lift up the house, put the new foundation in place, and then reset the house down in the same position. All the event content will be the same, but the underlying structure will be updated, and able to support our new features. After migration, any events you create will be made with the improved system.

The migration process uses a tool called Action Scheduler to handle the required tasks.

Will all my events be migrated?

When migration completes, every event in your site’s database is now using the new system. This includes past, current, and future events, as well as events of all post statuses. If during migration we detect an event that cannot be safely migrated, we will stop the migration and fully reverse the process. Either all of your events will be migrated, or none of them will–in which case your calendar will simply continue working with the old data system. See Troubleshooting below.

At this time, recurring events that have tickets or RSVPs cannot be migrated. We are not yet able to support that scenario in the new data system. However, we are working on a new feature that will allow you to migrate those events and provide basic functionality for Series Passes (read more). When we release that feature, we’ll also provide a migration path for folks with those events. In the meantime, you can hold off on migrating and continue to use plugins as you have been. If you want to migrate now, you’ll need to either remove the tickets/RSVPs from the event or change the recurring event to single events.

Note: You may notice that the number of events migrated does not match the number of events previously listed in the Events list table. This is because the old system counts each instance of a recurring event, while the new system counts a recurring event as one no matter how many occurrences it has.

How did the data storage system change?

In the previous implementation of Events Calendar Pro, we kept updated posts and meta fields for each occurrence of a recurring event. Each “child” event matched the “parent” except for the date and time. When a user created or edited an event, we had to create or update all those child posts, which could be time-consuming.

With the new system, we only have to maintain one post per recurring event. The distinct date and time information for each occurrence is stored efficiently in custom tables. This results in faster event management and calendar load times as there is considerably fewer data to update. While this change was prompted by necessary improvements to recurring events, it also means improved performance for all users of The Events Calendar–not just those with Pro.

As a part of this work, we transitioned The Events Calendar to use the iCalendar format. This change makes creating recurring events easier on the technical side, and opens up exciting possibilities for future features.

How long does migration take?

The amount of time it takes to migrate your events depends on your site configuration and the events themselves. In general, a site with thousands of events is going to take longer than a site with 100 events. Sites with many recurring events, especially events with multiple recurrence rules, may take longer to migrate. For many sites, migration takes only 5-10 minutes.

The first step of the migration process is the migration preview. During the preview, we’ll scan your existing events and give you an estimate of how long the migration itself will take.

The migration will progress fastest if you stay on the page at Events > Settings > Upgrades. If you navigate away, it will continue in the background but may go slower.

Can people access my site during migration?

Your site calendar and events will all be visible and accessible during migration. However, some functionality will not be available. Your site visitors will not be able to RSVP to events, purchase tickets, or submit their own events from the frontend. This is only the case during the actual migration, not the migration preview.

Can I edit my site during migration?

You will be able to access your site dashboard during migration. However, event functionality will be very limited. The following will be temporarily disabled or paused:

Creating or editing events, venues, or organizers
Adjusting Events or Tickets settings
Importing events via CSV, Eventbrite Tickets, or Event Aggregator

Once migration completes, all of these options will become available again. The functionality will only be limited like this during the migration itself, not the migration preview.

Other aspects of your site (anything unrelated to The Events Calendar) will be accessible the whole time, and the event migration will run in the background of anything else you’re doing.

How will migration affect my events?

The migration process transitions event data from our previous implementation to the new system. The new system uses custom tables to manage data much more efficiently, which results in faster updates and loading times. This is a major change on the fundamental level, but will have little to no visible impact on your events.

If you have Events Calendar Pro, you will see some changes to your recurring events. Content will be the same, but each recurring event will now be part of a corresponding Series of the same name. Series are a new way of grouping and displaying events that allow you to make complex sets of events with distinct content. On your calendar, events in a Series will be designated with an icon and/or display the Series name.

Complex recurring events with more than one pattern-based recurrence rule (e.g. an event happening daily at two different times, or monthly on the first and third Fridays) will be split during migration, with one recurring event for each pattern-based rule. The events will all still have identical content, and they’ll all be in the same Series. That means that they still appear together on your calendar, so there will be no discernible changes for your customers.

What happens if I don’t migrate?

You can run The Events Calendar 6.0 on your site without going through the migration process. However, you won’t have access to any of the new features, including improved performance. We’ll continue to support unmigrated sites for now, but many future features will also rely on your events being migrated to the new system.

Requirements

To begin migration, your site should have:

WordPress 5.6 or above
PHP 7.3 to 8.0
jQuery 3.5 and above
The Events Calendar 6.0+

If you have Event Calendar Pro, you must be using version 6.0+ to have access to migration.

Note: if you have a site database which does not support transactions (e.g. MyISAM), you will not be able to run a migration preview. You can still migrate events, but we won’t be able to provide a time estimate. Read more.

Migrating on sites with caching solutions

The migration process uses a tool called Action Scheduler to handle the required tasks. Migration requires repeating requests to your server, which may be flagged if you have aggressive caching options configured on your site. Sometimes, a caching tool completely blocks the process, resulting in a stuck migration preview or migration.

If your migration preview won’t start or seems to stall out part way through, it’s likely that caching options are the reason. You may need to temporarily deactivate or adjust caching solutions to complete migration. Once migration is done, you can restore your previous options.

For example:

If you have a caching plugin active (e.g. WP Rocket, W3 Total Cache), deactivate the caching plugin, complete migration, and then re-activate the caching plugin.
If you are using Cloudflare, try moving to the DNS-only option while running the migration. You can switch back after migration is complete.

Tips for a smooth migration

Be sure that you are using the latest version of The Events Calendar. Multiple migration issues have been fixed since the initial release of 6.0.
If possible, create a staging site and go through the migration process there first.
Backup your site’s database, just in case.
Confirm that your site uses PHP 7.4 or above, up to 8.0. Migration does not work well with PHP 8.1. Neither The Events Calendar nor WordPress itself fully supports this version yet.
Make sure that WP_Cron is enabled. Some hosts disable WP_Cron by default.
Review your Draft events. If you have any auto-draft events (i.e. events that you started to create but never saved), either manually save them or move them to Trash.
Review your trashed events. Restore any events you want to keep, then empty the trash.

Troubleshooting

Quick links:

Preview has been running for a long time, and the progress bar seems stuck.

If the preview has not started or has been in progress for several hours, first try clicking the Retry preview link or refresh the page. To speed up the preview and prevent another stall out, keep the page open at Events > Settings > Upgrades. If you navigate away, the preview will continue but at a slower speed.

The following are possible reasons the preview can slow down or get stuck:

There is a caching tool interfering. See Migrating on sites with caching solutions above.
WP_Cron is not active on your site. You may need to check with your hosting provider.
There are Pending actions under Tools > Scheduled Actions. You can run any Pending actions individually via that list, or use the wp cli command wp action-scheduler run to run all Pending actions.

I tried to do the migration preview and it says my system cannot run a preview.

Your site configuration does not support MySQL transactions, which means that we are not able to generate a preview report. You can still run the migration, we just won’t be able to provide you with a time estimate. If any events cannot be migrated, you’ll see the errors one at a time in the migration report.

The most common reason that a site doesn’t support transactions is because the database has a MyISAM table engine instead of InnoDB. MyISAM does not support MySQL transactions. If you are a developer and want to transition from MyISAM to InnoDB, you can follow this guide. Once you’re using InnoDB, you’ll be able to run a full migration preview.

The number of previewed events does not match the number of events I see in the Events list table.

Don’t worry! This happens because the old system counts each instance of a recurring event, while the new system counts a recurring event as one no matter how many occurrences it has.

You may notice a similar mismatch between the number of events previewed and the number of rows in the preview report. It’s for the same reason: the number of events previewed counts a recurring event as one, but each occurrence is listed out in the preview report.

I’m blocked from migrating because I have recurring events with tickets.

Migration errors – event data issues:

No occurrences created.
Event model does not have an RSET: it should at this stage.
The start_date should be a valid date
The provided timezone is not a valid timezone.
Invalid period in RDATE: start date must must be before end date.
Undefined index: same-time
Duration must be a positive integer. The end_date_utc does not match the value of end_date with the timezone.
Attempting to run Single Event strategy for recurring event. Is a strategy missing for this type of event?

Many of these errors have been mitigated by The Events Calendar 6.0.1. Please make sure you are running the latest version of the plugin(s).

If you do see these errors, it’s likely because the event(s) have corrupt or missing data. Open the event and check for any blank fields in the dates, times, or recurrence options. Save the event and try again. If the error appears again, try removing and re-creating the recurrence rule(s).

If the problematic event is a Draft, either re-save it or trash and delete it. If it’s in the trash, empty the trash.

If you’ve tried the suggestions above and are still seeing errors, the best next step is to deactivate all third-party plugins and then try migration again. We’ve found this is one of the most-consistent fixes for customers with persistent errors. Once migration is successful, you can reactivate everything.

Migration errors – PHP 8.1:

TECEventsCustom_TablesV1ModelsEvent implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary)
[DateTime::__construct(): Passing null to parameter #1 ($datetime) of type string is deprecated]

These errors occur when your site is using PHP 8.1. Neither The Events Calendar nor WordPress itself fully supports this version yet. Adjust your site to use PHP 7.4 or 8.0 in order to complete migration and avoid other related issues.

Other migration errors

If you encounter an error other than the ones listed above, go through the following steps and then try again:

Make sure you are using a location-based timezone for your website.
Review the problematic event(s) and look for missing or corrupted data, particularly around dates, times, and recurrence options. Fix any data issues and re-save the event.
Deactivate all third-party plugins. Once migration is complete, you can re-activate any deactivated plugins.

I migrated and event pages are showing 404 errors.

Try the following:

Flush your permalinks by going to Settings > Permalinks and clicking Save Changes.
Re-save the event without making changes. If it’s a recurring event, be sure to select the Save for all events option.
Edit the event, change the start date, then change it back (so it’s correct) and save. If it’s a recurring event, make sure that the recurrence rules are correct when you save, since changing the start date can impact the rules.

You may also be experiencing a known issue with Events Calendar Pro 6.0.2. We are working on a fix for this issue.

Migration is stuck and I can’t access the Events section of my site.

If your migration has been running for several hours with no change, go to the Upgrades tab and keep the page open there. This will speed up the migration process and bypass some possible issues. Leaving the page open forces the site to process events in batches of 10 without using the Action Scheduler tool. If you want to adjust the batch size, you can use this snippet.

The following will help the migration process go faster and not get stuck:

Deactivate all third-party plugins, especially any that involve caching. You can reactivate these once migration is complete.
Make sure that WP_Cron is active on your site.
In your dashboard, go to Tools > Scheduled Actions and look for any Pending actions. Use the row actions to run any Pending actions manually, or use the wp cli command wp action-scheduler run to run all Pending actions at once.

If you’ve completed the above steps and migration has still not progressed after another hour, you can completely reset the migration process. However, this should only be done as a last resort. We have used this option during our own development work, but it has not been specifically tested for general use.

Running this snippet will revert the event metadata and custom tables, and reset your site back to a state where you can re-try migration. This will force your site out of the maintenance mode we use during migration.

Install the free Code Snippets plugin.
In your dashboard, go to Snippets > Add New and copy the snippet below.
Save and Activate the snippet.
Go to Events > Settings > Upgrade and confirm that migration is not longer in progress.
Go back to Snippets > All Snippets and deactivate the snippet.

Before you try migration again, you may want to review our tips for a smooth migration.

The snippet:

add_action( 'init', function () {
  // Will attempt to force a revert of tables and metadata
  tribe( \TEC\Events\Custom_Tables\V1\Migration\Process_Worker::class )->undo_event_migration( [] );
} );

Reversing migration

For one week after you complete migration, you have the option to reverse the migration by clicking Reverse migration under Events > Settings > Upgrades. The reversal may take as long as the original migration and your site will go back into maintenance mode for that time. Keep in mind that reversing the migration will return your events to the state they were in before migration. This means that any updates you made to events after migration will be lost during the reversal process. This option is only recommended in extreme cases where you absolutely must go back to the old data system.

If you still need help, you can contact support. Please include as much information as possible including error text, screenshots or video, your WP_DEBUG log, and export of the preview or migration report.