Troubleshoot WordPress Publishing

Overview

WordPress publishing in CntX depends on four layers working together: correct integration credentials (site URL, username, Application Password), reachable REST API, proper user capabilities in WordPress, and valid content item state (body present, destination mapped, editorial gates acknowledged). Failures usually surface as connection test errors, CMS failed status on the item, or silent success pointing at the wrong environment.

This guide walks through quick checks in order of frequency—most incidents resolve with URL typos, revoked Application Passwords, security plugins blocking `/wp-json/`, or strategy destinations pointing at another workspace’s integration. Editorial approval warnings are intentional; they do not block publish unless your workflow chooses to wait.

Keep editorial status and CMS status separate while debugging. Fixing WordPress does not change whether a brief was approved internally, and approving internally does not prove the post reached the CMS.

When to use

Use this troubleshooting guide when:

• Test connection fails in Settings → Integrations.
• Publish actions return 401, 403, 404, or CMS failed.
• Posts appear on the wrong site (staging vs production, or another client’s domain).
• Content publishes but categories, SEO meta, or formatting are wrong or missing.
• REST works in browser tests from your laptop but fails from CntX (host firewall, geo block, bot protection).

If you have not connected WordPress yet, complete Connect CntX to WordPress first.

Before you start

• Confirm which workspace owns the integration and content item.
• Have WordPress admin access to verify posts and Application Password list.
• Know whether security plugins, CDN rules, or HTTP basic auth protect the site.
• Copy the exact error message from CntX toast or CMS status field before changing settings.

Quick checks

Work through this list before deep configuration changes:

1. Site URL format — Must be `https://domain.com` without `/wp-admin`, trailing slashes on wrong paths, or http/http mismatch. Mixed content redirects can break API clients.
2. Application Password validity — Regenerate if rotated, revoked, or copied incompletely. WordPress shows one display only at creation time.
3. Publishing user capabilities — User must publish posts (Editor/Administrator). Subscriber-level accounts return 403 on create.
4. REST reachability — Open `https://yoursite.com/wp-json/` in a browser. Expect JSON, not HTML login page, 404, or firewall challenge.
5. Correct workspace integration — Strategy destination must reference the integration for the workspace you are editing—not another brand’s WordPress connection.
6. Content item readiness — Title and body populated; channel mapped to WordPress destination.
7. Categories still exist — Deleted WordPress categories mapped in CntX may cause publish errors depending on API strictness.
8. Editorial warning acknowledged — CntX may warn when publishing before Approved; confirm you did not cancel the action accidentally.

Common symptoms and fixes

401 Unauthorized or 403 Forbidden

Likely causes: Wrong username, wrong Application Password, revoked password, or insufficient role.

Fix:

1. WordPress → Users → Profile → Application Passwords: revoke old `CntX` password, create new.
2. Update integration in CntX Settings → Integrations; run test connection.
3. Confirm user role includes `publish_posts`.
4. If using two-factor or SSO plugins, ensure Application Passwords remain enabled for API users.

404 on `/wp-json/` or REST routes

Likely causes: Permalink structure, security plugin blocking REST, or host WAF.

Fix:

1. WordPress → Settings → Permalinks → save Post name structure (flushes rewrite rules).
2. Security plugin: allow REST API / disable “Disable REST API” toggles.
3. Host panel: whitelist `/wp-json/*` from bot fight mode (Cloudflare, Sucuri, etc.).
4. Confirm site is not maintenance-mode walled for anonymous requests.

Connection test passes but publish fails

Likely causes: Category mapping, custom post type mismatch, payload validation, or plugin rejecting content HTML.

Fix:

1. Publish draft with minimal body to isolate content issues.
2. Remove problematic embeds or shortcodes; retry.
3. Check WordPress Site Health and error logs (`debug.log` if enabled).
4. Temporarily disable conflicting SEO or content filtering plugins to bisect.

Published to wrong environment

Likely causes: Staging URL in production workspace or duplicate integrations.

Fix:

1. Compare integration URL in CntX with intended public domain.
2. Rename integrations clearly (`WP Production`, `WP Staging`).
3. Audit strategy channel destinations after URL correction.
4. Delete erroneous draft posts on wrong site to avoid duplicate SEO URLs.

Missing Yoast SEO title or meta description

Likely causes: Yoast meta not exposed to REST, or CntX field mapping incomplete for your plugin version.

Fix:

1. Verify Yoast REST API support for your Yoast version.
2. Set meta manually in wp-admin after draft publish until mapping confirmed.
3. Inspect REST response for `yoast_head_json` or meta fields when debugging with browser or curl.

CMS status stuck or stale

Likely causes: Transient API error, timeout on large HTML, or manual edits in WordPress desyncing state.

Fix:

1. Retry publish from CntX—updates existing post ID when stored.
2. Open WordPress post list to confirm actual state vs CntX CMS badge.
3. Reconcile external URL on content item if slug changed manually in wp-admin.

SSL or certificate errors

Likely causes: Expired cert, incomplete chain, TLS version blocked by host.

Fix: Renew certificate; test with SSL Labs; ensure HTTPS redirects do not loop.

Expected result

After fixes, Test connection succeeds in Settings → Integrations. Publishing a sample item sets CMS draft or CMS published, displays external link, and creates visible post in WordPress admin with expected title and body. Repeat publish updates same post rather than duplicating.

Security plugins remain enabled with REST allow rules rather than globally disabled. Team documents which Application Password belongs to which environment.

Tips

• One password per environment — Never reuse staging credentials on production integration.
• Draft-first debugging — Always validate with draft publish before live push when testing fixes.
• Log preservation — Screenshot error toasts; WordPress `debug.log` timestamps help support if you escalate.
• Multisite WordPress — REST paths and user accounts differ; confirm network admin guidance for Application Passwords on subsites.
• HTTP auth staging — Basic auth in front of staging blocks API unless CntX supports auth headers in your build; use publicly reachable staging or IP allow lists.
• Do not disable REST globally — Other integrations depend on it; prefer targeted allow rules.

Next step

Re-test the integration, publish a draft, verify in WordPress admin, then proceed to Publish Content as a Draft or Live Post for ongoing workflow. If errors persist after these checks, Contact Support and Report a Security Issue with workspace ID, integration URL (redact password), and exact error text.