# Divi 4 → 5 Migration Guide

> Migrate a Divi 4 site or portfolio to Divi 5 with Royal MCP Pro's divi_convert_shortcodes_to_blocks tool: audit, back up, verify, and undo if needed.

- Canonical: <https://royalplugins.com/support/royal-mcp-pro/divi-migrator-guide/>
- HTML version: <https://royalplugins.com/support/royal-mcp-pro/divi-migrator-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](https://royalplugins.com/support/royal-mcp-pro/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](https://royalplugins.com/support/royal-mcp-pro/#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:

1. **External backup first** (SiteVault, host snapshot, whatever your normal DR path is).
2. **Dry-run audit** to see the full picture.
3. **Migrate in batches of 5-10 pages** by passing explicit `post_ids` arrays. Each batch gets its own undo token.
4. **Verify each batch on the front end** before starting the next. Any batch that goes wrong is undone individually while other batches stay migrated.
5. **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**](https://royalplugins.com/support/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](https://royalplugins.com/support/royal-mcp-pro/undo-token-errors/) — if step 5 fails or your token expired
- [Pro tool returned upgrade prompt with valid license](https://royalplugins.com/support/royal-mcp-pro/pro-tool-returned-upgrade-prompt/)

### 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](mailto: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)

[← Divi Pro Tools](https://royalplugins.com/support/royal-mcp-pro/divi-tools/)
[Divi Page Cloning →](https://royalplugins.com/support/royal-mcp-pro/divi-page-cloning-workflow/)