Reference
Hacks & Gotchas
Real issues encountered while building — not hypothetical.
x REST API returns 404 for everything
Cause: WordPress permalinks set to default numeric format.
Fix: Settings -> Permalinks -> Post name -> Save. Do this first, every time.
Fix: Settings -> Permalinks -> Post name -> Save. Do this first, every time.
x ACF fields missing from API response
Cause: ACF REST API exposure is off by default.
Fix: In ACF field group settings, enable "Show in REST API". Also ensure CPT registration has show_in_rest => true.
Fix: In ACF field group settings, enable "Show in REST API". Also ensure CPT registration has show_in_rest => true.
x WordPress images do not load in Next.js
Cause: WordPress hostname not in next.config.ts remotePatterns, or Hostinger hotlink protection blocks external requests.
Fix: Add hostname to remotePatterns. In hPanel, disable Hotlink Protection or whitelist your Vercel domain.
Fix: Add hostname to remotePatterns. In hPanel, disable Hotlink Protection or whitelist your Vercel domain.
x CORS error in browser console
Cause: WordPress does not allow cross-origin requests by default.
Fix: Add add_cors_headers() to functions.php. During development, temporarily use * as the allowed origin.
Fix: Add add_cors_headers() to functions.php. During development, temporarily use * as the allowed origin.
x Published posts do not appear on live site
Cause: Next.js ISR has cached the old version. Without a webhook it never updates.
Fix: Set up the revalidation webhook (Phase 5).
Fix: Set up the revalidation webhook (Phase 5).
x WordPress content renders unstyled
Cause: WordPress content is raw HTML. Your CSS does not target elements inside dangerouslySetInnerHTML.
Fix: Add className="prose prose-lg max-w-none" using @tailwindcss/typography.
Fix: Add className="prose prose-lg max-w-none" using @tailwindcss/typography.
x CF7 form returns 404
Cause: Wrong API endpoint path.
Fix: Use /wp-json/contact-form-7/v1/contact-forms/ID/feedback. Get the ID from the CF7 admin URL (?post=123).
Fix: Use /wp-json/contact-form-7/v1/contact-forms/ID/feedback. Get the ID from the CF7 admin URL (?post=123).
x Subdomain not working after DNS change
Cause: DNS propagation takes time (up to 48h).
Fix: Wait and verify at dnschecker.org or run dig cms.yourdomain.com in terminal.
Fix: Wait and verify at dnschecker.org or run dig cms.yourdomain.com in terminal.
x Build is very slow (generateStaticParams)
Cause: Pre-rendering hundreds of pages at build time.
Fix: Only pre-generate the 20 most recent. Set dynamicParams = true so older pages generate on first request.
Fix: Only pre-generate the 20 most recent. Set dynamicParams = true so older pages generate on first request.
x wp-admin unreachable after going headless
Cause: WordPress is now at cms.yourdomain.com but team visits old URL.
Fix: Add redirect in vercel.json. Bookmark cms.yourdomain.com/wp-admin.
Fix: Add redirect in vercel.json. Bookmark cms.yourdomain.com/wp-admin.