Troubleshooting

Connection issues

"Webhook URL not configured"

Go to Altered Digital → Settings and set the Service URL to your Worker URL. The webhook URL auto-populates from {service_url}/webhook/wp.

"Test Connection" fails

1. Verify the Service URL is reachable from your server (some hosts block outbound requests).
2. Check that the Webhook Secret in the plugin matches the Worker's stored secret.
3. If behind a firewall, allowlist the Worker's IP range (Cloudflare Workers egress).

"not_authenticated" on analyze/quote

Your AD account session expired. Go to Altered Digital → Onboarding Wizard → Step 1 and log in again. The JWT is refreshed automatically on each login.

Migration issues

Posts show "pending" forever

1. Check the Worker logs for errors.
2. Verify your Sanity API token has write permissions.
3. Run wp altered-digital status to see the local log.
4. If the Worker's D1 shows the post as success but WP shows pending, the REST /status/post/{id} reconciliation hasn't run — trigger it by viewing the post in the admin.

"sanity_quota_exceeded" error

Your Sanity project hit its API quota or rate limit. Options:

• 402 (quota): Upgrade your Sanity plan or wait for the monthly quota reset.
• 429 (rate limit): Wait a few minutes and re-publish. The Worker retries automatically on the next webhook.

The webhook returns HTTP 503 with an actionable message so the plugin can surface the right guidance.

Featured image missing in Sanity

The asset upload failed. Check the Worker logs for assetErrors. Common causes:

• The WP media file is too large (Sanity has a 100MB limit per asset)
• The media URL returns 403 (hotlink protection on the WP server)
• The WP wp:featuredmedia embed is missing (the plugin should always include it)

Posts save without mainImage when the asset upload fails — no placeholder is written.

Elementor post looks wrong

1. Check the Worker logs for AI_FALLBACK_NEEDED — the deterministic parser couldn't handle the widgets.
2. Run AI Cleanup after migration to refine the output.
3. Unknown Elementor widget types route to AI transform fallback automatically.

WPBakery nested shortcodes

Shortcodes nested deeper than 3 levels yield confidence 0 → AI fallback. If the AI service is also unavailable, the content falls back to the HTML parser (graceful degradation). The post still migrates, but the layout may be flattened.

WP-CLI timeout

For very large sites, wp altered-digital export may hit PHP's max_execution_time. Increase it:

wp --exec="set_time_limit(0)" altered-digital export --limit=5000

Or run in smaller batches with --offset:

wp altered-digital export --limit=500 --offset=0
wp altered-digital export --limit=500 --offset=500

Duplicate hooks

The plugin guards against duplicate transition_post_status hooks with has_action() at priority 99. If you see double-firing webhooks, another plugin may be re-adding the hook — check with:

wp hook list transition_post_status

Still stuck?

Contact support at ryan@altereddigital.com, or use the Priority Support add-on for Slack-based help.