Operations And Troubleshooting

This page covers how to confirm Divine 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 Divine is active, a short end-to-end pass tells you that every layer is wired up correctly. Confirm that the Divine menu loads for an administrator, that the workspace opens, and that your installed theme appears as an app, which together prove the admin app, the REST surface, and the theme registry are reachable. Then exercise the build loop: create a worktree, edit one file, and watch it appear in the review panel. Run dv check . from inside the theme, open the worktree in the canvas and in the signed browser preview, and deploy the accepted file back into the app theme. If each of those succeeds, the registry, the filesystem, preview signing, git inspection, the check runtime, and the deploy path are all functioning.

The Divine Admin Is Not Visible

If the Divine menu does not appear, start with the current WordPress identity and the install type, because the two interact. Divine is gated by its management capability, and that capability differs between install types. On a single-site install the capability defaults to manage_options, so an administrator account sees the menu in the normal admin. On a multisite network the capability is manage_network, and Divine registers only in network admin, so you must be a super admin and you must be looking in network admin rather than a single site’s dashboard. A user who can open Divine on a single-site install will not necessarily see it on a network, because the network requires the higher capability. See Multisite for how the two surfaces differ.

A REST Route Returns 404

When a route such as /wp-json/divine/v1/apps returns a 404, work through the usual causes in order. First confirm the plugin is active, since the routes are only registered when Divine loads. Then verify the basics of the request: that the path really is under /wp-json/divine/v1/, that you are using the correct HTTP method, and that permalinks have been flushed by opening Settings, Permalinks and saving, which re-registers REST routes a stale rewrite cache may be hiding. A 401 or 403 is an authentication or capability problem rather than a missing route; the request reached Divine but the user lacked the management capability.

Worktree Creation Fails With A Git Error

Worktree creation copies the app theme’s git repository so Divine can inspect changes without a git binary, so it requires the source theme to be a git repository. When creation fails with a git error, the source theme has no .git directory. Initialize and commit the theme once so the repository exists, then create the worktree again:

cd wp-content/themes/your-theme
git init
git add -A
git commit -m "Initial theme state"

dv check Reports Unexpected Findings

When dv check reports findings you did not expect, the usual cause is a mismatch between what you think it inspects and what it actually inspects. dv check validates the theme directory you point it at, on its own merits, regardless of whether that theme is registered as a Divine app. Its scope is the path, so running it from the wrong directory checks the wrong files; pass the theme path explicitly, or run dv check . from inside the theme, to be sure of the target.

The findings also depend on which layers run. Fast mode, the default, runs the divine, blockstudio, and tailwind layers entirely in PHP without booting WordPress, opening network connections, or shelling out. It does not run the WordPress render layer, so it cannot report render-time problems and will not flag anything that only surfaces when the page is actually rendered. Add --full to include the wordpress layer, which performs a render dry-run and needs a WordPress bootstrap. You can also narrow or widen the run with --layers=divine,blockstudio,tailwind,wp. A realistic, well-formed theme run in fast mode returns no findings; unexpected findings on such a theme almost always mean a real static issue in the layers that ran, not a false positive, so read the finding rather than discount it.

dv check Cannot Resolve The Divine Check Runtime

If dv check reports that it could not resolve the Divine check runtime, the generated dv shim ran but could not find Divine’s code to delegate to. The full message is:

Could not resolve Divine check runtime. Set DIVINE_AUTOLOAD or install the Divine plugin.

The shim finds Divine in one of three ways, in order. It first honors the DIVINE_AUTOLOAD environment variable when it points at a readable bootstrap file. It then looks for a divine-runtime/ bundle inside the theme itself, which is what an exported theme carries. Finally it walks up from the theme directory, up to eight ancestors, looking for the Divine plugin as plugins/divine, mono/apps/divine, or apps/divine. The error means all three failed: there is no usable bundle in the theme, the plugin is not installed where the walk-up can reach it, and DIVINE_AUTOLOAD is unset. Resolve it by either installing or locating the Divine plugin at one of the expected ancestor paths, or by setting DIVINE_AUTOLOAD to a reachable Divine bootstrap so the shim can load the runtime directly.

dv show Requires A WordPress Bootstrap

The dv show command builds URLs against the live WordPress runtime, so it needs a database-connected WordPress to resolve them. On a Local-by-Flywheel-style install, running dv show from a raw shell often fails because the database is reachable only from inside the site’s own environment, not from an arbitrary php process. You will see a resolution error that lists what Divine probed and ends with the line:

Run inside the site's wp-cli context, pass --url/--site for multisite, or set DIVINE_WORDPRESS_BOOTSTRAP to a reachable wp-load.php.

A related symptom is an Error establishing a database connection surfaced through the probe, which means Divine found a WordPress to load but could not reach its database from where you ran the command. The most reliable fix is to let WP-CLI bootstrap WordPress for you, because it knows the site’s connection details: run dv show where the wp binary resolves the site, which on stacks like Local usually means running inside the site shell. If WP-CLI is not available, point Divine straight at the right entrypoint by setting DIVINE_WORDPRESS_BOOTSTRAP to a reachable wp-load.php. On a network, also pass --url or --site so Divine targets the correct subsite while it bootstraps.

dv show Reports A Theme Is Not Registered

When dv show reports that an app is not registered, it resolved an app slug that does not match a registered Divine app or, on a network, a known network site. This commonly happens when the theme directory name differs from the installed stylesheet, because dv show resolves the app from the WordPress-backed stylesheet rather than from the folder name alone. It asks WordPress which theme occupies that directory and uses that stylesheet as the app, so a directory whose name does not match the registered stylesheet still resolves correctly as long as WordPress can map it. The failure means that mapping did not land on a registered app.

Resolve it by naming the target explicitly. Pass --app with the correct app slug, or on a network pass --site or --url to select the site whose active theme you mean. Naming the site is also what disambiguates a network where more than one site could match, since the error Network site "..." was not found. means the selector did not match any site in get_sites(). See Multisite for how site selection works.

A Worktree Page Shows A 404 In The Browser But Renders In The Canvas

This is expected behavior, not a bug. The canvas and the in-app browser preview render worktree pages in two deliberately different ways. The canvas renders a worktree page from its theme file directly, as a virtual render, so a page that exists only in the worktree appears in the canvas immediately. The in-app browser opens the real, clean site URL for that page, and a worktree-only page has no corresponding WordPress URL yet, so WordPress returns a 404 for it.

The difference is the point. Worktree pages are theme files under pages/; they are not added to the WordPress pages list, and the native block editor does not edit them. They become real URLs only after the worktree is deployed and the files land in the app theme. So a new worktree page rendering in the canvas while 404ing in the browser is the system working as designed. Use the canvas to review worktree-only pages, and expect the browser to serve them only once they are deployed.

A Preview Link Shows The Live Theme

A signed preview fails closed: when its parameters are invalid, Divine ignores them and renders the live theme rather than leaking the worktree. So a preview link that shows the live site almost always means the link is no longer valid. The URL may have been altered, which invalidates the signature; the WordPress salts may have changed; or the worktree may have been deployed or destroyed, so there is nothing left to preview. Copy a fresh URL from the workspace and try again. A share link behaves the same way: expired, revoked, or edited links render the live site.

Deploy Is Blocked By Conflicts

Deploy refuses to mirror files while git reports conflicted files in the worktree, because promoting a half-resolved merge would push ambiguous content into the app theme. Open the review panel, resolve each conflict in the merge view, and deploy again. Deploy stays files-only throughout: it mirrors theme files into the app theme and never copies posts, options, uploads, or database state.

Multisite Deploy Targets The Wrong Site

On a network, deploy promotes worktree files into the selected site’s active theme only, and it identifies that site by blog_id. If a deploy seems to land on the wrong site, the cause is almost always that the operation resolved a different site than you intended, which is easy when several network sites run a theme with the same stylesheet name. The fix is to make the site target explicit so resolution is unambiguous. Confirm you are operating on the intended app, whose slug is site-{blog_id}, and pass the site or blog target when a command accepts one. Deploy never fans out across the network, so naming the right site is what keeps the files going to the right theme. See Multisite for the per-site model.

Theme Export Fails

The dv export command and the export REST route package a theme into a zip, and export errors usually name the missing prerequisite. The most common one is that the PHP ZipArchive class is unavailable, because building the zip requires the PHP zip extension; install or enable it and export again. Other named causes are that the uploads directory is not writable, or that the scoped runtime package is incomplete in a source checkout. For source checkouts, build the scoped runtime libraries before exporting so the bundled divine-runtime/ is complete.

divine.json Changes Have No Effect

Performance configuration is validated strictly, and an invalid file is ignored as a whole rather than partially applied. Invalid JSON, unknown keys, wrong value types, or incompatible data policy settings all cause the theme config to be discarded so a malformed file cannot silently change runtime behavior. Enable measurement headers to see the effective profile and config hash in responses, which tells you whether your file was accepted.

Static Prerender Serves Stale Or No Pages

The static prerender cache only stores anonymous GET requests for clean HTML paths, so it deliberately bypasses anything that should stay dynamic. Logged-in users, query strings, admin, REST, AJAX, cron, feeds, and search always bypass it. To confirm a path is being served from the cache, look for X-Divine-Static-Prerender: HIT in a logged-out request. For a hard reset, delete wp-content/uploads/divine-static-prerender/; it rebuilds on demand.

The Workspace Loads A Development Server Unexpectedly

Divine loads the Vite dev server when it is configured to, which is correct in development and surprising anywhere else. Outside development environments, unset DIVINE_UI_APP_DEV_SERVER, DIVINE_UI_APP_DEV_SERVER_AVAILABLE, and DIVINE_ENV_ROLE. With DIVINE_ENV_ROLE=dev, Divine assumes the dev server should be used and will try to load it; clearing these makes Divine serve the built bundle instead.

Cleaning Up Operational Artifacts

Divine writes a few operational directories under uploads that are safe to prune. wp-content/uploads/divine-exports/ and wp-content/uploads/divine-static-prerender/ can be deleted and will be recreated on demand. Worktrees are different: end them through deploy or destroy rather than deleting theme directories by hand, so the registry record is removed together with the files. Deleting a worktree directory manually leaves a stale registry entry behind.