# Troubleshooting — Start Here

> Royal MCP Pro troubleshooting hub: start with the Free guide, which covers about 80% of Pro-tier issues, then work through the Pro-specific patterns.

- Canonical: <https://royalplugins.com/support/royal-mcp-pro/troubleshooting-start-here/>
- HTML version: <https://royalplugins.com/support/royal-mcp-pro/troubleshooting-start-here/>

---

Something isn't working on your Royal MCP Pro install. This page is the master triage — find the row that matches your symptom and follow the link to the detailed doc. Most Pro-tier failures actually resolve at the Free troubleshooting layer first because the underlying MCP-connection surface is shared. Start there before assuming it's a Pro-specific bug.

### The 80/20: start with the Free troubleshooting guide

Roughly 80% of tickets we receive on Royal MCP Pro turn out to be host-layer or MCP-connection issues that would fire the same way on Free tier. Cloudflare / Imunify360 / BitNinja / StackCDN intercepting the OAuth handshake. Host WAF blocking outbound POSTs to my.royalplugins.com. Claude Desktop connector dropping tool calls before they reach WordPress. None of that is Pro-specific — and it's all covered end-to-end in the Free guide.

If your symptom is "Claude can't connect," "OAuth failed," "ofid\_… error," "tool call timed out," or "connector says reconnect" — go there first. Come back to Pro-specific docs only if the Free guide rules that layer out.

[Open Free Troubleshooting — Start Here →](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/)

## Pro-specific symptom triage

The four situations below are Pro-only. If your symptom matches one of these, the Free guide won't help — jump straight to the linked doc.

### License won't activate

You entered your Purchase Email + License Key on the License page and clicked Activate, but got an error notice. The license itself is fine on [My Account](https://my.royalplugins.com/my-account/licenses/), but activation on this site refuses to complete.

#### Common variants

- "License activation failed" (server rejected the key — wrong plugin, wrong email, expired, at limit)
- "License server error" (host WAF blocking outbound HTTPS to my.royalplugins.com)
- "Invalid response from license server" (CDN interstitial mangling the response body)
- "Please enter a license key" (form submitted with a blank field)

[Open License Activation Issues →](https://royalplugins.com/support/royal-mcp-pro/license-activation-issues/)

### Pro tool returns upgrade prompt with valid license

The License page shows the key as active, the activation-count moved up by one on My Account, but when you call a Pro tool from your MCP client, the response comes back as an upgrade prompt (`🔒 {tool_name} is a Royal MCP Pro feature.`) anyway.

#### Almost always caused by

- A sibling Royal Plugin Pro (ForgeCache, FormForge, GuardPress, Royal Affiliate Pro) loading its older SDK copy first — via the WordPress alphabetical plugin-load order — and shadowing Royal MCP Pro's newer SDK
- Object cache holding a stale "invalid" license transient
- SDK bootstrap failure (rare — opcache serving stale bytecode, corrupt install)

[Open Upgrade Prompt with Valid License →](https://royalplugins.com/support/royal-mcp-pro/pro-tool-returned-upgrade-prompt/)

### Undo tool returned an error

You called `royal_mcp_undo_last_operation` with the token from a prior Pro tool response, but it returned an error instead of reversing the operation. Every possible error code has a specific fix.

#### The 6 possible codes

- `token_not_found` — empty arg, wrong string, or purged row (past 30-day retention)
- `token_consumed` — already used once (tokens are one-shot)
- `token_expired` — past its TTL (72h default, 168h for SEO / Widget / Redirection bulk)
- `undo_handler_missing` — tool's undo handler not loaded (plugin deactivated after write, or upgrade broke mapping)
- `undo_handler_failed` — data state changed since original write, handler threw
- `insufficient_caps` — you're not the original actor and lack override caps

[Open Undo Token Errors →](https://royalplugins.com/support/royal-mcp-pro/undo-token-errors/)

### Pro tool refused with "builder session detected"

You called a Divi or Elementor Pro write tool and it came back with `builder_session_active` instead of the change you asked for. The tool detected an active editor session on the target post and refused to write — not a bug, a deliberate guard against silently clobbering someone's in-progress editor work.

#### Three resolutions

- Close the editor tab and retry (safest — guaranteed no auto-save collision)
- Wait ~150 seconds for the WordPress edit lock to go stale, then retry
- Pass `force=true` to the tool call to explicitly acknowledge the risk and proceed anyway

[Open Builder Session Detected →](https://royalplugins.com/support/royal-mcp-pro/builder-session-detected-force-override/)

## Combined symptoms — hybrid patterns

Sometimes a ticket looks Pro-specific but is really two problems stacked. A few common combinations:

### "Pro tools work fine, but every tool call takes 20+ seconds"

Almost never a Royal MCP Pro issue. Usually the licensing server call is timing out on your host's outbound path and the SDK is retrying. Check outbound HTTPS to `my.royalplugins.com` from your server. Fix: host allowlist for that domain, or (if you've verified the license state locally) reduce the SDK's check-in frequency via the `wpgenius_license_check_interval` filter.

### "Everything works from Claude Desktop but fails from Claude.ai web"

Free-tier surface issue, not Pro. Claude.ai's web connector uses OAuth for auth; Claude Desktop typically uses API keys. If OAuth is broken (host WAF, CDN interstitial, ChatGPT DCR mismatch) then only the OAuth-based client fails. Free troubleshooting guide covers this.

### "Pro tool call succeeds but the change didn't take"

Almost always a page cache. Royal MCP Pro writes to the DB successfully, but the visitor-facing page is served from ForgeCache / LiteSpeed Cache / WP Rocket / edge CDN's cache. Clear the page cache and reload. This is why the `wp_publish_and_promote_pro` composer includes a ForgeCache purge step — use it whenever you write and want the change immediately visible.

### "Pro tool call succeeded, but Divi/Elementor front-end still shows old content"

Same class as the above — but specifically, Divi and Elementor both maintain their own CSS caches (Divi's static CSS, Elementor's inline-CSS storage). A content write via MCP triggers post-content dirty state, but the builder's CSS file cache may not regenerate until the next admin visit to the page in the editor. Fix: visit the page once in the editor to trigger regeneration, or clear the builder's CSS cache from its settings.

## Before you email support — 4-line diagnostic

Regardless of which symptom matches, gathering these four data points before you email speeds up a support ticket dramatically:

1. **Which Royal Pros are active on the site + what versions** (Plugins page). This surfaces the sibling-SDK-shadow case at a glance.
2. **Which MCP client + which tool + the exact response text**. Paste the full response, not a paraphrase. Error codes are load-bearing.
3. **Does the same call work from a different client?** (e.g. from Claude Desktop if Claude.ai web fails, or vice versa). Isolates client-side vs. server-side.
4. **Screenshot of the Pro tool row in Audit Log** with View Details expanded (WP admin → Royal MCP Pro → Audit Log). Shows what the plugin actually did vs. what you thought it did.

Having all four in the initial email cuts a typical ticket resolution from 2-3 round-trips down to one.

## Still Stuck? Two-Step Support Path

If your symptom doesn't match any of the above, and the Free troubleshooting guide didn't help either, contact us directly.

### Step 1: Try the Free Troubleshooting Guide first (if you haven't yet)

[**Royal MCP Troubleshooting — Start Here**](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/) covers the MCP-layer diagnostic tree in depth. If you skipped it, run through it once now — the majority of "unexplained Pro issues" resolve there.

### Step 2: Email priority support

If the Free guide + one of the Pro-specific docs above still doesn't get you unstuck, 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 (the 4-line diagnostic above, plus)

- **Your hosting provider** (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, self-hosted VPS, etc.)
- **Royal MCP Pro version** from WP Admin → Plugins
- **WordPress + PHP versions**
- **Active caching plugins** (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
- **Active security plugins** (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
- **Cloudflare or CDN** in front of the site? If yes, is "Manage AI Bots" or "Bot Fight Mode" on?
- **Which steps you tried from this doc + the Free guide** and what changed at each

[← Support Overview](https://royalplugins.com/support/royal-mcp-pro/)
[License Activation Issues →](https://royalplugins.com/support/royal-mcp-pro/license-activation-issues/)