Operations And Troubleshooting

This page covers how to confirm Onumia is healthy after setup and how to diagnose the failures you are most likely to meet in practice. Each section describes the symptom you will see, why it happens, and how to resolve it.

Sanity Check After Setup

Once Onumia is active, a short end-to-end pass tells you that every layer is wired up correctly. Confirm that the Onumia admin page loads for an administrator and that its settings routes respond without REST 404s, which together prove the admin app and the REST surface are reachable. Check that role capabilities and sandbox defaults are both visible in Settings, and that the managed database drop-in is installed. Then exercise the agent path: connect a client to /wp-json/onumia/mcp, load onumia://context, create a sandbox, run on help and wp help, and open the sandbox’s preview URL. If each of those succeeds, the control plane, the command surface, and previews are all functioning.

The Admin Page Is Not Visible

If the Onumia admin page does not appear, start with the current WordPress identity. Administrators with manage_options should see it. Other users need either Onumia capabilities through their role or a sandbox shared with them; without one of those, the menu stays hidden even though the user can still log in to WordPress. If the app appears but Settings is missing or blocked, that is expected for non-administrators because configuration remains admin-only.

A REST Route Returns 404

When a route such as /wp-json/onumia/v1/settings/capabilities returns a 404, work through the usual causes in order. First confirm Onumia is active, since the routes are only registered when the plugin loads. If it is active, flush WordPress rewrite rules by opening Settings, Permalinks and saving, which re-registers REST routes that a stale rewrite cache may be hiding. Then verify the basics of the request itself: that you are using the correct HTTP method, that the path really is under /wp-json/onumia/v1/, and that no security plugin or firewall is blocking REST API traffic, which is a common and easily missed cause.

MCP Connection Fails

The MCP transport requires an authenticated WordPress user; anonymous access is never allowed. If a client cannot connect, confirm it is pointed at /wp-json/onumia/mcp and that the request authenticates as a real WordPress user. The user must hold the Onumia capabilities needed for whatever the agent attempts, and because agents authenticate with Application Passwords, those must be enabled on the site. If all of that is in place and the connection still fails, the most likely remaining cause is the client not sending credentials correctly, so verify how it is configured to pass the Application Password.

Sandbox Creation Fails Because The Database Is Too Large

Local cloning enforces a size budget, which defaults to a 250 MB copied row payload. When a sandbox cannot be created because the database exceeds that budget, you have a few ways to bring the copied payload down before resorting to raising the limit. Mark noisy tables as schema-only so their structure is copied but their rows are not, exclude tables that the sandbox does not need at all, and redact large or sensitive columns so rows still exist without their bulky contents. Only after trimming the payload should you consider raising the limit deliberately, and on a genuinely large production database that is rarely the right move. If local cloning simply is not appropriate for the site’s scale, the better path is an external database integration rather than forcing a large local clone through.

Sandbox Creation Fails Because The Size Is Unknown

By default Onumia refuses to clone when it cannot estimate the database size, because proceeding blind risks side effects on a database that turns out to be enormous. Some hosts prevent the size inspection Onumia relies on, which produces this exact failure even on a perfectly reasonable database. If you have separately verified that local prefix cloning is safe on your site, you can allow unknown-size clones to proceed:

add_filter('onumia/database/allow_unknown_size_local_clone', '__return_true');

Use this only with that host-level confidence, since it removes the guard that otherwise protects you from an unbounded clone.

A db.php Conflict Blocks Setup

Onumia routes sandbox database traffic through a managed db.php drop-in. If an unmanaged db.php already exists, Onumia will not overwrite it, because that file frequently belongs to the host or another plugin and silently replacing it could break the site. The resolution is investigative rather than mechanical. Find out what created the existing drop-in, determine whether the host or another plugin depends on it, and only then decide whether Onumia may manage db.php or whether the two systems need a custom integration to coexist. Never delete a host-managed drop-in without first understanding the hosting requirement it satisfies.

WP-CLI Commands Fail

When wp commands fail, the cause is usually that Onumia cannot find or is not permitted to run the binary. Confirm WP-CLI is installed, and if wp is not on the process path, point Onumia at the right binary with the ONUMIA_WP_BIN constant or the onumia/wp/bin filter. If the binary is fine, the failure may be policy rather than dispatch: the command may require a capability the user lacks, it may use a blocked site-selection flag, or it may exceed the runtime timeout. A quick way to confirm dispatch itself is working is to run wp help through execute; if that returns, WP-CLI is reachable and the problem lies with the specific command.

Write Commands Are Blocked

Onumia classifies commands by intent, and any command it considers a sandbox write requires the execute_write capability. If a write is rejected, the user simply does not hold that capability. The write classification covers content and option mutations such as wp option update and wp post create, filesystem changes such as mkdir, rm, and mv, and shell behavior that writes, including tee, shell redirection, and sed -i. Grant execute_write to the role if the user should be allowed to make changes inside sandboxes.

Eval Commands Are Blocked

The wp eval and wp eval-file commands require the separate execute_eval capability, which is intentionally distinct from ordinary write access because evaluating arbitrary PHP is far more powerful. Even when a user holds execute_eval, Onumia still blocks high-risk eval behavior such as process execution, dynamic function calls, external includes, and unsafe filesystem access. A blocked eval therefore means either the capability is missing or the code crosses one of those hard limits.

A Preview Link Fails

A preview link can fail for several mundane reasons. The sandbox must still be active and its preview token must not have expired, since a discarded or expired sandbox no longer has valid preview state. The URL must be intact, because any change to it invalidates the token, and the browser must accept cookies, since previews rely on them. Finally, the site must be reachable under the sandbox’s site URL. When in doubt, generate a fresh preview URL with preview_sandbox and try again.

The Workspace Looks Too Small Or Shows WordPress Chrome

This is expected behavior in Onumia Pro Workspace rather than a fault. Enable Full screen to hide the WordPress admin interface and let the Workspace fill the viewport, and enable Hide header to also remove the Onumia header for a clean canvas. Both toggles persist between sessions, so the layout you choose stays put.

Database Merge Is Not Configured

The database merge workflow depends on MerQL and a configured PDO connection to the live database. If merge operations report that nothing is configured, supply the connection. The usual approach is constants in wp-config.php:

define('ONUMIA_MERQL_DSN', 'mysql:host=localhost;dbname=wordpress;charset=utf8mb4');
define('ONUMIA_MERQL_USER', 'db_user');
define('ONUMIA_MERQL_PASSWORD', 'db_password');

If you would rather build the connection in code, provide a ready PDO instance through the filter instead:

add_filter('onumia/data/merql_pdo', fn (?PDO $pdo): PDO => $customPdo);

A Database Merge Has Conflicts

A merge reports conflicts when the sandbox and the live database have changed the same row identity in incompatible ways, so there is no safe automatic resolution. Do not apply a plan while conflicts remain. Resolve the underlying cause of the divergence first, then create a fresh plan so it reflects the current state of both sides rather than re-staging stale changes.

Rollback Aborts Because Rows Drifted

Rollback verifies that the live rows it is about to restore have not changed since the promotion. When it detects that they have drifted, it aborts by default to avoid silently overwriting newer live changes with older sandbox values. This is a safety stop, not an error. Only set force to true after you have reviewed the drift and consciously accept that the rollback will overwrite the newer data.

Audit Review

The Onumia activity log is your primary tool for understanding what happened after the fact. Use it to trace who triggered a given tool, what input was sent and what output came back, which sandbox was targeted, which promotion operation produced rollback data, and which errors occurred. Because those records can contain full tool input and output, treat the log as sensitive operational data and control access to it accordingly.