Divi 4 → 5 Migration Guide

End-to-end walkthrough for migrating a Divi 4 site — or a whole portfolio of them — from shortcode-based Divi 4 to block-based Divi 5, using Royal MCP Pro's divi_convert_shortcodes_to_blocks tool. Audit, back up, defer to Divi's own migrator, verify, undo if needed.

Read this first: what the tool does and does NOT do

Elegant Themes has not published a programmatic migration API. divi_convert_shortcodes_to_blocks does not perform the actual shortcode-to-block conversion itself. What it does is:

Audit every Divi post and count the D4 / D5 / mixed / not_divi state
Optionally snapshot every Divi 4 post's post_content into a recoverable meta key so you have a rollback path
Return Divi's admin URL where you (or the AI agent) click "Migrate This Site to Divi 5" to trigger the conversion inside Divi's own UI
Provide a 72-hour undo token that restores the backed-up posts if the migration goes sideways

The value is the audit + backup + safety net around the migration, not the conversion itself. Divi still owns the conversion.

Prerequisites

Divi theme installed — a version that includes the built-in "Migrate This Site to Divi 5" feature (Divi 5.x). If you're still on Divi 4.x with no Divi 5 available, the tool can audit and back up, but there's no Migrator button to click yet.
Royal MCP Pro installed and licensed (see Getting Started)
manage_options capability — this tool is admin-only because it snapshots and can restore post_content across the whole site
MCP client connected to your site
Strongly recommended: a fresh SiteVault (or equivalent) backup before running the commit step, in addition to the tool's own postmeta snapshot

The full migration workflow

End to end, this is a 5-step flow. The tool handles steps 1, 3, and 5; Divi's own admin handles step 4; you (or your agent) drive the process.

Dry-run audit

Ask your AI to call divi_convert_shortcodes_to_blocks with defaults. dry_run defaults to true, so nothing is written — you just get a report.

Run divi_convert_shortcodes_to_blocks on my site.

The response includes counts of every Divi post by format:

[dry-run] 47 posts scanned — D4: 31 · D5: 12 · mixed: 3 · not_divi: 1.
Divi does not expose a programmatic migrator. Visit https://yoursite.com/wp-admin/admin.php?page=et_theme_options#... and click "Migrate This Site to Divi 5" to convert.

You now know exactly what state your content is in before touching anything.

Review the counts and decide scope

Look at the per-post results array in the response. Every entry has post_id, format_detected, and title. Decide:

Do you want to migrate everything (all D4 and mixed posts)? Skip the post_ids arg in step 3.
Do you want to migrate a subset (e.g., only /services/ pages, or only specific templates)? Pass an explicit post_ids array in step 3 to scope the backup.

Migrating in batches is safer — migrate 5 pages, verify, migrate the next 5.

Commit with backup (writes begin here)

Call the tool with dry_run: false. Every Divi 4 post has its current post_content snapshotted into a recoverable meta key (_royal_mcp_pro_divi_pre_migration_backup) before Divi's Migrator runs.

Run divi_convert_shortcodes_to_blocks with dry_run: false, backup: true, and post_ids: [42, 108, 143].

The response includes a 72-hour undo token you'll use in step 5 if anything goes wrong. Full MCP envelope shape:

{
  "isError": false,
  "content": [
    {
      "type": "text",
      "text": "3 posts scanned — D4: 3 · D5: 0 · mixed: 0 · not_divi: 0. Backed up 3 posts. Divi does not expose a programmatic migrator. Visit https://yoursite.com/wp-admin/admin.php?page=et_theme_options#... and click \"Migrate This Site to Divi 5\" to convert."
    }
  ],
  "structuredContent": {
    "results": [
      { "post_id": 42, "format_detected": "divi_4_shortcodes", "title": "Services", "backup_written": true },
      { "post_id": 108, "format_detected": "divi_4_shortcodes", "title": "About", "backup_written": true },
      { "post_id": 143, "format_detected": "divi_4_shortcodes", "title": "Contact", "backup_written": true }
    ],
    "counts": { "divi_4_shortcodes": 3, "divi_5_blocks": 0, "mixed": 0, "not_divi": 0 },
    "total_scanned": 3,
    "backed_up_post_ids": [42, 108, 143],
    "migrator_admin_url": "https://yoursite.com/wp-admin/admin.php?page=et_theme_options#...",
    "dry_run": false,
    "positioning_note": "This tool audits and prepares. Elegant Themes has not published a programmatic migration API — the actual conversion is triggered from the Divi admin UI."
  },
  "undo": {
    "token": "<64-character-hex-token>",
    "expires_at": "2026-08-08T14:23:15Z",
    "ttl_hours": 72
  }
}

Copy the undo token now. Save it somewhere you'll find it in the next 72 hours — you'll want it if step 5 uncovers a problem.

What your AI actually shows you

The content[0].text string is the human-readable summary your AI client (Claude, ChatGPT, Cursor) will paraphrase into chat. The structuredContent object is the machine-readable version the agent uses to plan next steps. The undo block sits at the top level and is standardized across every destructive Pro tool.

Trigger Divi's Migrator in wp-admin

The migrator_admin_url in the response is a best-effort link to where the Migrator lives in the Divi admin (currently under Divi → Theme Options). Open that URL in wp-admin.

Find the "Migrate This Site to Divi 5" button and click it. This is where the actual shortcode-to-block conversion happens — the tool doesn't do this part, Divi does.

If the URL doesn't land you on the Migrator

Elegant Themes moves admin pages between Divi releases. The URL is best-effort — if the anchor doesn't scroll to the Migrator, look manually under Divi → Theme Options, Divi → Support Center, or Divi → Divi 5 Migration depending on your Divi version. Report the correct location back so we can fix the tool's URL in a future release.

Verify results (and undo if needed)

Once Divi's Migrator finishes, re-run the audit with dry_run: true to confirm the format flip:

Run divi_convert_shortcodes_to_blocks with dry_run: true on the same posts I just migrated.

The counts should show those posts as divi_5_blocks now instead of divi_4_shortcodes. Load the pages on the front end and click around — check the header, buttons, images, forms, and any custom modules.

If anything looks wrong — missing modules, broken layout, corrupted content — use the undo token from step 3 to restore the pre-migration snapshot:

Undo the migration with royal_mcp_undo_last_operation using token <64-character-hex-token>.

The tool's undo_migration_snapshot handler:

Writes the backed-up post_content back to every affected post
Deletes the _royal_mcp_pro_divi_pre_migration_backup meta on each restored post (frees the slot for a future re-migration)
Fires ET_Core_PageResource::remove_static_resources() per post so Divi's per-post CSS cache doesn't serve the post-migration styles for restored Divi 4 content

Front-end pages now render from the pre-migration Divi 4 shortcodes again. If you want to try the migration again after fixing the underlying issue, note that your original snapshot is gone — the next commit run will take a fresh snapshot from whatever post_content is present at that moment.

Tool signature reference

Arguments

Name	Type	Default	Description
`post_ids`	`array<integer>`	none	Optional. If omitted, scans all posts/pages with `_et_pb_use_builder=on`. Pass explicit IDs to scope the operation.
`dry_run`	`boolean`	`true`	Report without writing anything. Default true so accidental calls are safe.
`backup`	`boolean`	`true` when `dry_run=false`	Snapshots D4 `post_content` into `_royal_mcp_pro_divi_pre_migration_backup`. Only fires when actually committing (dry_run=false).
`post_types`	`array<string>`	`["post", "page"]`	Post types to include in the scan.

Response fields

The response is wrapped in the standard MCP tool-call envelope. The content[0].text field is the human-readable summary; the structuredContent object holds the machine-readable payload; the top-level undo block is added when a snapshot was written.

Inside `structuredContent`

Field	Description
`results`	Per-post array. Each entry: `{post_id, format_detected, title, backup_written?}`.
`counts`	Rollup by format: `{divi_4_shortcodes, divi_5_blocks, mixed, not_divi}`.
`total_scanned`	Total post count included in this run.
`backed_up_post_ids`	Post IDs that had a fresh snapshot written (only on commit runs).
`migrator_admin_url`	Best-effort URL to Divi's admin Migrator button.
`dry_run`	Echoes the mode this call ran in.
`positioning_note`	String explaining the tool's audit-and-prep positioning — safe for the agent to relay to the user.

Top-level `undo` block (only when a snapshot was written)

Field	Description
`token`	64-char hex token to pass to `royal_mcp_undo_last_operation`.
`expires_at`	ISO-8601 UTC expiration timestamp (with trailing `Z`).
`ttl_hours`	Undo window in hours. Default 72.

Safety guards built in

Dry-run default. Any accidental call is safe by default because dry_run is true unless explicitly set false.
Existing-snapshot check. The backup step will not overwrite an existing _royal_mcp_pro_divi_pre_migration_backup if one is already present. Your first snapshot for a given post is the one preserved — re-runs don't overwrite it with post-migration content.
72-hour undo window. The undo token can restore all backed-up posts in one call. Cap-checked to the original actor OR royal_mcp_pro_undo_any / manage_options / super-admin (see Undo Tokens).
Audit Log row on every call. Both dry-run and commit runs write a row to the Universal Audit Log for compliance and post-mortem visibility.
Not a converter. Because the tool doesn't perform the actual shortcode-to-block conversion, it can't corrupt content by getting the conversion wrong. The worst case is a bad backup snapshot — which is why the SiteVault-style external backup is still the belt-and-suspenders recommendation for large migrations.

Portfolio-scale scenario (~47 pages)

For an agency migrating a client site with 30-50 Divi 4 pages, the safe cadence is:

External backup first (SiteVault, host snapshot, whatever your normal DR path is).
Dry-run audit to see the full picture.
Migrate in batches of 5-10 pages by passing explicit post_ids arrays. Each batch gets its own undo token.
Verify each batch on the front end before starting the next. Any batch that goes wrong is undone individually while other batches stay migrated.
Clean up snapshots after 72 hours by consuming the undo tokens as "no-op restore" (the SDK doesn't currently expose a token-discard endpoint — snapshots naturally age out of the undo store on TTL expiry).

Common issues

Tool returns `insufficient_caps`

This tool requires the manage_options capability because it snapshots and restores post_content across the whole site. If your MCP session is authorized as an editor or a lower role, upgrade the acting user to admin or run with an admin's OAuth token / API key.

Migrator URL doesn't land on the button

See the note in Step 4 above — Elegant Themes moves admin pages between Divi releases and the tool emits a best-effort URL. Search manually under Divi → Theme Options, Divi → Support Center, or Divi → Divi 5 Migration.

Backup meta already exists

If you commit twice in a row, the second commit won't overwrite the first snapshot — the first (pre-first-migration) content stays preserved as the recovery point. Response's backed_up_post_ids only lists posts where a FRESH snapshot was written this call. Posts with existing snapshots are still scanned/counted but don't add a new backup.

Divi's Migrator errored inside its own UI

That's an Elegant Themes issue, not a Royal MCP Pro issue — contact ET support with what Divi's Migrator UI reported. Meanwhile, your pre-migration snapshot is still stored in postmeta and you can use the undo token to restore your content while ET investigates.

I want to redo a migration after fixing a Divi module

Fine to re-run. But note: the existing-snapshot check means your original pre-migration content is the recovery point, not the state before your second attempt. If you want a fresh snapshot mid-migration, delete the _royal_mcp_pro_divi_pre_migration_backup post meta manually via wp-cli or a plugin like Advanced Custom Fields before re-running the tool.

Still Stuck? Two-Step Support Path

If the migrator prep isn't running correctly, work through these two steps in order.

Step 1: Start with the Royal MCP Troubleshooting Guide

Royal MCP Troubleshooting — Start Here covers MCP-layer issues (Claude can't connect, connector fails, ofid_xxxxx errors). If the tool call itself never lands on your site, that guide is where to start.

For Pro-specific patterns:

Undo token errors — if step 5 fails or your token expired
Pro tool returned upgrade prompt with valid license

Step 2: Email priority support

If you've worked through Start Here and the relevant Pro-specific doc and the migration prep still isn't working, email priority support from your purchase email address at support@royalplugins.com. Priority email support is included with your license — typical response within 24 hours. Never include your license key in email; we look it up from your purchase address.

What to include in your email

Your hosting provider (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, Liquid Web, self-hosted VPS, etc.)
Royal MCP Pro version from WP Admin → Plugins
Divi version from Appearance → Themes (click the active Divi theme card) OR your Divi Builder plugin version from WP Admin → Plugins
Active caching plugins (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
Active security plugins (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
Which MCP client — claude.ai web custom connector, Claude Desktop with mcp-remote, ChatGPT MCP, Cursor, or another MCP-compatible client
The dry-run audit output (counts + first few results entries) so we can see the state your posts are in
The exact error message from the tool call, or the exact error Divi's Migrator UI showed if the failure was inside Divi's admin
Screenshot of the Pro tool row in Audit Log for the failed call, with View Details expanded
Which step from the workflow above failed (1 dry-run, 2 review, 3 commit, 4 Divi Migrator button, or 5 verify/undo)