Troubleshooting

Every cwp error carries a fix hint. These are the ones that come up often enough to earn a page.

cwp doctor says the package path does not match. The package value in cwp.yml disagrees with the real remote wp-content location. Set it to managed or developer to match what doctor probed. A wrong value sends files to the wrong path on push.

Images are broken locally. You are on --uploads skip, or proxy mode is off. Run cwp media pull --uploads proxy, or --uploads sync for a full copy. See uploads strategies.

Fonts, generated CSS or background images 404 while images are fine. The uploads fallback is running as the mu-plugin, which only covers what WordPress renders (B-019). Run cwp doctor; it names the mechanism and the reason. The usual cause is a .ddev/config.yaml that does not say webserver_type: nginx-fpm. Add it, then run cwp media pull and ddev restart.

The uploads fallback exists but serves nothing. .ddev/nginx/*.conf takes effect only after ddev restart. If it persists, check that the remote serves the file without HTTP authentication. A login in front of the site breaks the fallback, and cwp media pull --uploads sync is the way around it.

The local site sends real email. It should not: every pull that imports a database installs the mail guard. If you imported one by hand instead of through cwp db pull, run cwp scrub to install the guard.

cwp refuses a deploy to production. Production is protected, and the refusal is the safety guard working. Pass --force only when you mean it.

A remote wp command fails with a root error. cwp retries with --allow-root and caches the result. If it persists, run the host’s own wp --info to see the raw error.

A pull aborts on the pre-pull snapshot. cwp refuses to replace the local database when it could not create a restore point, and at that point the import has not started. Usually the DDEV project is not running: ddev start, then pull again. cwp db pull --no-snapshot proceeds without a restore point. Use it only when you know nothing local is worth keeping.

cwp db list fills up with pre-pull-… snapshots. Every pull leaves one and nothing prunes them. Delete the ones you no longer want with cwp db rm.

Cloudron CLI not found. npm i -g cloudron, then cloudron login <host>.

Known upstream defects

Four defects in Bricks 2.4 affect what cwp can do. This page names them instead of hiding them behind a workaround. All four surfaced against 2.4-beta2. 2.4 is still in beta and a later build may have fixed any of them. Know that before you plan around a workaround:

• B-016 — the HTML converter’s class IDs are not the IDs the classes get.

• B-017 — every Bricks items ability pages at 25 and says so quietly. cwp ability warns for that reason and offers --all.

• B-018 — a custom Bricks query type never gets the loop’s post context.

• B-059 — the write abilities refuse any element whose link setting is a string, on the theory that link is always a link object. On the image gallery it is a select (lightbox, attachment, media, custom), so one gallery refused the write for a whole page.

  cwp works around this one, because the alternative is a page that cannot go up at all. The tree goes up through the ability without that key. The ability still takes the revision and sanitises the payload, and cwp writes the key into the stored element tree afterwards. The run names every such setting:

  ✓ page/ueber-uns — image-gallery.link = lightbox on #abcde4 — written past the builder's own check

  cwp itself refuses a value outside the four. It reports a write that does not land rather than assuming it: Bricks silently discards changes to its own meta keys for a user without builder access.

They live in BUGS.md in the repository, with the mechanism of each.

A host that forbids unfiltered HTML

Cloudron’s WordPress defines DISALLOW_UNFILTERED_HTML, and so do many managed hosts. It means no user holds unfiltered_html, not even an administrator. So the page builder escapes <, > and & inside element settings when it saves. Most of that is harmless: & in a paragraph is correct HTML and renders as &.

Two cases are not harmless, and cwp repairs both after the write (B-061):

• a condition’s comparison operator: >= stored as >= matches nothing, so the element silently stops rendering;
• CSS with a child selector: #hero > * stored as #hero > * stops applying.

The run names each restored element. What it cannot do is stop the escaping: the host enforces that policy inside WordPress. If an element the target changed in some other way comes back different, the push says so and exits non-zero. That one is not a repair cwp can justify making for you.