WordPress troubleshooting

Before troubleshooting

The single fastest test: in Settings → Integrations → WordPress, click Test connection. If it fails, the error message there is more specific than the generic "publish failed" you may have seen.

Then check the per-publish log: every publish records a structured log entry under Settings → Audit log with the exact HTTP code, response body, and the URL we POSTed.

401 Unauthorized

Caused by:

1. The application password was revoked or rotated. Generate a new one in WordPress and re-paste. See Connecting WordPress.
2. The user no longer exists. A removed WP user invalidates their application passwords. Use a different admin user.
3. The username field is wrong. WordPress wants the login username, not the display name or the email.

Fix: rotate the application password, double-check the username (WP Admin → Users → row → username column).

403 Forbidden

Most common cause: a security plugin blocking REST API access.

Wordfence: Wordfence → Firewall → All Firewall Options → Rate limiting, allow your publish IP range, or disable "Block REST API" if it's on. The publish IPs are listed at our status page; we have a small number of them.

iThemes Security: Security → Settings → REST API, set to Default Access, not Restricted Access.

If you don't run a security plugin, check that your hosting provider isn't doing the blocking — some managed hosts (e.g. Kinsta, WP Engine) require a support request to permit programmatic REST access from external IPs.

404 Not Found on the REST endpoint

WordPress 5.6+ has the REST endpoint at /wp-json. Two reasons it might 404:

1. Permalinks not flushed. Visit WP Admin → Settings → Permalinks and click Save (no changes needed — the click flushes rules).
2. Pretty permalinks disabled. With plain permalinks, the endpoint is /?rest_route=/wp/v2/. Switch to any pretty permalink structure (Post name is fine).

422 Validation error

The post body failed WordPress validation. Common causes:

• A required custom field is missing. Check the field mapping at Settings → Integrations → WordPress → Field mapping.
• HTML the engine produced isn't sanitised by your WP theme. We strip aggressively before POST, but custom blocks can still trip filters.
• Featured image URL is unreachable. Test the image URL in a private window.

Publish hangs

If publish never completes, the WP REST endpoint is likely behind a slow plugin (caching, image-optimisation) timing out. Bump the publish timeout at Settings → Integrations → WordPress → Advanced → Request timeout. The default is 30 seconds; safe to raise to 60.

If a 60-second timeout doesn't help, the WP install is severely overloaded — there's nothing the integration can do.

Featured image not setting

Two failure modes:

1. Media upload succeeded but featured image didn't attach. We upload the image, then PATCH the post with featured_media: <id>. If the second call fails, the image is orphaned in your media library. Re-publish to retry.
2. Image URL was inaccessible during upload. Hot-linked images sometimes block server fetches. Re-upload via the editor's drag-drop instead — that hosts the image on our side.

Categories and tags not setting

If your post publishes but lands without categories / tags:

• Confirm the categories exist on the WP side. We don't auto-create — we look them up by slug.
• Check the slug, not the display name. "Marketing Strategy" → slug marketing-strategy.

Auto-create-on-publish for categories and tags is on the roadmap.

Repeated 5xx

If you see persistent 502 / 503 / 504, the WP server is the problem. Our retry policy is two attempts with exponential backoff; after that we surface the error and stop. The job stays in the publish queue and you can retry manually after the WP side recovers.