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 events to take advantage of the new features.

How do I know if I need to migrate my events?

The best way to check if your site requires migration is to go to Events > Troubleshooting and view your System Information. Search for Custom Tables Migration Status. If it says Incomplete, you need to migrate. If it says Not Required or Completed, your events do not need to be migrated.

How do I migrate my events?

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 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?

Once migration completes, every event in your site’s database is 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.

Recurring events with RSVPs cannot be migrated. Our system does not support this scenario. In order to migrate, you’ll need to remove the RSVPs, convert them to free tickets, or make the recurring events into 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.

If you have any tickets on recurring events, those tickets will be converted to Series Passes. Series Passes grant the attendee access to all events in the Series (i.e. every occurrence of the recurring event). We recommend you review any generated passes and make sure they meet  your site’s ticketing needs.

What happens if I don’t migrate?

You can run The Events Calendar 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.

My site doesn’t have any events. Why am I being prompted to migrate?

If you were using a 5.x version of The Events Calendar, your site is set up to create and look for data in the old method. Even if you have no past or upcoming events, you need to go through the migration process so that events you create in the future use the new system.

However, the migration process will not start if there are no events. To migrate a site with no events, you’ll need to make a single placeholder event. You can use the Hide From Event Listings option to prevent it from showing on your calendar. Once you create the event, go through the migration process. It should go very quickly with a single event. Once that’s done, you can simply delete the placeholder event and you’re all ready to create real events in the future.

Requirements

To begin migration, your site should have:

  • WordPress 5.8.6 or above
  • PHP 7.4 or above
  • jQuery 3.5 and above
  • The latest version of The Events Calendar

If you have Event Calendar Pro, you must be using the latest version there as well.

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.
  • 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.
  • Make sure that WP_Cron is enabled. Some hosts disable WP_Cron by default.
  • Check your WP Memory usage with this plugin. If the usage percentage is over 75%, consider upping your site’s WP Memory limit.
  • 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. Try deactivating your caching plugin(s) and try again. (See Migrating on sites with caching solutions above).
  • Your site’s WP Memory is low. You can use this plugin to check your memory usage. If the usage percentage is over 75% when you try to run the preview, that’s likely the issue. Increase your WP Memory limit and try again.

If you’ve ruled out those issues and the preview is still getting stuck, you can try skipping the preview. Follow these steps:

  1. Install the free Code Snippets plugin.
  2. In your dashboard, go to Snippets > Add New and paste in this snippet: add_filter( 'tec_events_custom_tables_v1_db_transactions_supported', function(){ return false; } );
  3. Save and Activate the snippet.
  4. Go to Events > Settings > Upgrade, start the migration preview, and keep the page open. You’ll get a note that says the preview cannot be processed but you can still try to migrate.
  5. Start the migration process and stay on the page.
  6. After migration completes, go back to Snippets > All Snippets and deactivate the snippet.

For the majority of customers, one of the above strategies will help with a stalled preview. If you’re still having trouble, please contact support and be sure to include your site’s system information and a copy of your site’s debug log.

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 RSVPs.

Recurring events with RSVPs cannot be migrated. Our system does not support this scenario. In order to migrate, you’ll need to remove the RSVPs, convert them to free tickets, or make the recurring events into single events.

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?

Firstly, 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). You can also save the event as a Draft, then re-Publish it. That can help regenerate missing data.

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 error – Migration was canceled. Please try again.

This error means that some other process blocked the migration. This is often caused by caching plugins. Deactivate or disable caching solutions and try migrating again. Once migration is complete, you can re-enable caching tools.

In you use WP Engine, you may need to contact your host to temporarily disable caching at the server level.

Other migration errors

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

  1. Make sure you are using a location-based timezone for your website.
  2. 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.
  3. 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.
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.
  • Check your WP Memory with this plugin. If the usage percentage is over 75% when you try to migrate, that can cause the process to stall. Increase your WP Memory limit and try again.

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.

  1. Install the free Code Snippets plugin.
  2. In your dashboard, go to Snippets > Add New and copy the snippet below.
  3. Select Only run once.
  4. Go to Events > Settings > Upgrade and confirm that migration is not longer in progress.

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( ['started_timestamp' => 1] );
} );

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.

If it’s been more than a week, you can force site back to the old data system. However, the same warnings as above apply and data could be lost if you edited or created events after migrating. This option is only recommended in extreme cases where you absolutely must go back to the old data system. 

If you need to revert the migration and are okay with the risks, follow these steps:

  1. Install the free Code Snippets plugin.
  2. In your dashboard, go to Snippets > Add New and copy the snippet below.
  3. Select Only run once.
  4. Save and Activate 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( ['started_timestamp' => 1] );
} );

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.