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:

User opens Visual Builder / Elementor editor / Gutenberg on post 42 at 12:00:00
Royal MCP writes new post_content via REST at 12:00:15
Editor auto-saves at 12:00:30 — its in-memory state (from before your REST write) is what hits the DB
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 Pro tool that writes to an existing post's post_content or builder-managed postmeta runs the guard at the top of its handler. As of Royal MCP Pro 1.0.2:

Divi Pro (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_to_page, 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 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. 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