# Builder Session Detected — Force Override

> Royal MCP Pro returned builder_session_active because a Divi or Elementor editor tab is open on the post. When to close the editor and when to use force=true.

- Canonical: <https://royalplugins.com/support/royal-mcp-pro/builder-session-detected-force-override/>
- HTML version: <https://royalplugins.com/support/royal-mcp-pro/builder-session-detected-force-override/>

---

You called a Divi or Elementor Pro tool that modifies an existing post, and it came back with `builder_session_active` instead of the change you asked for. The tool detected an editor session open on that post and refused to write — not a bug, a deliberate guard against silently clobbering someone's in-progress editor work. This doc walks through when the guard fires, when to close the editor, and when to pass `force=true` to override.

The message you're looking at

`Refused: post 42 has an active editor session (opened 30 seconds ago by janedoe). Close the editor tab or pass force=true to override. This guard prevents your write from being silently overwritten by the editor's next auto-save.`

Structured content includes `error: builder_session_active`, `post_id`, and a `builder_session` object detailing when the lock was set, who set it, and how long ago.

## Why the guard exists

The failure mode without the guard:

1. User opens Visual Builder / Elementor editor / Gutenberg on post 42 at 12:00:00
2. Royal MCP writes new `post_content` via REST at 12:00:15
3. Editor auto-saves at 12:00:30 — its in-memory state (from before your REST write) is what hits the DB
4. Your REST write is silently overwritten. No error on either side. The user later notices their MCP change didn't take.

This is a real class of bug that WordPress core's `_edit_lock` exists to signal — every builder (Divi 4 & 5, Elementor, Gutenberg, Bricks, Beaver Builder, Oxygen) sets and reads it because it lives in core. Royal MCP Pro just checks the same postmeta and refuses to write when the lock is fresh, exposing the collision as a hard soft-error instead of letting it happen silently.

## How the guard decides a session is active

The guard reads `_edit_lock` postmeta on the target post. WordPress writes this in the format `<timestamp>:<user_id>` when a user opens the editor, and the editor's Heartbeat API refreshes the timestamp every ~15 seconds while the tab has focus.

The guard considers the session **active** when the timestamp is less than **150 seconds** old (matching WordPress core's `EDIT_LOCK_TIME` default). Older than 150s means the editor was closed / crashed / navigated away, and it's safe to write past the stale lock.

The guard refuses even when you ARE the lock-holder

Earlier versions of the guard let the lock-holder skip the check. That opened the exact hole the guard was meant to close — the failure mode fires whenever the editor tab is open, regardless of whether it's you or a colleague. Editor auto-save clobbers the REST write ~30s later either way. Fresh lock = refuse, period. If you know the editor is closed but the 150s window hasn't lapsed yet, use `force=true`.

## Three ways to resolve it

### Option A: Close the editor tab (correct answer 90% of the time)

The safest resolution — guarantees no auto-save can clobber your MCP write.

Find the browser tab where the editor is open on that post and close it. WordPress's heartbeat stops firing, the lock goes stale within 150 seconds, and the guard clears itself.

If you don't know which tab has the editor open, check the `editor_user_login` field in the error's structured content — that's the user with the lock. If it's you, look for a Divi / Elementor / block-editor tab you left open. If it's a colleague, message them.

### Option B: Wait ~150 seconds and retry

Works when the editor was already closed but the lock hasn't gone stale yet.

The heartbeat only refreshes the lock while the editor tab has focus. If someone opened the editor 60 seconds ago and immediately closed it, the lock still has ~90 seconds of freshness left even though the tab is gone. Just wait it out.

Response's `builder_session.seconds_since` field tells you exactly how old the lock is — subtract from 150 to know how long you'd wait.

### Option C: Pass `force=true` to the tool call (agent-driven acknowledgement)

Use when you KNOW the editor is closed but the lock is still fresh, or when you accept the auto-save-collision risk.

Every Pro tool guarded by `Builder_Safety` accepts a `force` boolean argument. Pass `force=true` and the guard short-circuits — write proceeds.

```
Call divi_replace_image on post 42 with old_url="...", new_url="...", force=true.
```

**Only use this when you actually know the state.** If you force-override while someone's editor is genuinely open, they'll lose the work between their last save and their next auto-save.

## Which tools carry this guard

Every builder-writing tool that touches an existing post's `post_content` or builder-managed postmeta runs the guard at the top of its handler:

- **Divi (5 tools)**: `divi_replace_image`, `divi_import_template`, `divi_library_update`, `divi_library_delete`, `divi_apply_global_preset`
- **Elementor Pro (7 tools)**: `elementor_apply_template_advanced`, `elementor_create_widget`, `elementor_update_widget`, `elementor_update_widget_setting`, `elementor_delete_widget`, `elementor_apply_theme_builder_conditions`, `elementor_bulk_replace_widget_setting`

Tools that create fresh posts (e.g. `divi_clone_page`) don't need the guard because the target post-ID is one they just created and no one has the editor open on. Tools that touch settings or read data (audit / list / get) don't run the guard either.

## Common surprises

### "I closed the editor 10 seconds ago and the guard still fires"

Expected. The lock lingers for up to 150 seconds after the last heartbeat. Wait it out, or force-override if you're confident.

### "I never opened an editor and the guard still fires"

Someone else did — check the `editor_user_login` field. On multi-admin sites, another admin may have left an editor tab open. Common on agency sites where multiple people touch the same site.

### "The `editor_user_login` field is null but `active` is true"

Very old WP versions occasionally wrote just `<timestamp>` to `_edit_lock` without a user\_id. The guard treats that as an anonymous lock — still respects the timestamp, just can't tell you who set it.

### "My server clock is off by hours; every lock looks fresh / stale"

If your server is *ahead* of the actual time, real locks look expired. If it's *behind*, expired locks look fresh. Both cases are a server-config issue — run `ntpdate` or the equivalent on your VPS. Managed hosts should get this right automatically.

### "I passed `force=true` and it still errors on something else"

Force only skips the Builder\_Safety guard — it doesn't skip cap checks, input validation, license gates, or any other tool-specific error path. If you're getting a different error after adding force, that's a separate problem.

## Still Stuck? Two-Step Support Path

If the guard fires when no editor is (or ever was) open on the post, 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 that can look like guard failures (e.g. tool call reaching the wrong post ID due to search-result confusion).

### Step 2: Email priority support

If the guard is definitely firing on a post that has no editor session, 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 full `builder_session` object** from the error response (all 7 fields — especially `since`, `editor_user_id`, and `seconds_since`)
- **The tool name and args** that produced the error
- **Which builder** is active on that post (Divi 4, Divi 5, Elementor, Gutenberg, other)
- **Royal MCP Pro version**
- **Whether other users are known to be admins on the site** (rules the "colleague left tab open" case in or out)
- **Server timezone + current server time** (rules out clock skew)
- **Output of `SELECT * FROM wp_postmeta WHERE post_id = {N} AND meta_key = '_edit_lock';`** where N is the post ID — shows the raw lock value the guard is reading

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