Reference
Troubleshooting
Step-by-step diagnosis for the most common issues.
Diagnosing API Issues
Always start here. Run these curl commands in order and stop at the first failure:
# 1. Is WordPress reachable at all?
curl -I https://cms.yourdomain.com
# Expected: 200 OK or 301
# 2. Is the REST API enabled?
curl https://cms.yourdomain.com/wp-json
# Expected: JSON with "namespaces" array
# 3. Can you fetch posts?
curl "https://cms.yourdomain.com/wp-json/wp/v2/posts?per_page=1"
# Expected: JSON array
# If HTML -> permalink issue (Settings -> Permalinks -> Post name)
# 4. Are embedded images included?
curl "https://cms.yourdomain.com/wp-json/wp/v2/posts?per_page=1&_embed" | grep source_url
# Expected: image URLs in outputBuild & Deploy Failures
| Error | Cause | Fix |
|---|---|---|
Invalid src prop on Image | WordPress domain not in remotePatterns | Add hostname to next.config.ts |
NEXT_PUBLIC_WP_API_URL is undefined | Env var not set in Vercel | Add it in Vercel Settings → Environment Variables |
Type error: Property acf does not exist | Using WPPost instead of WPProject type | Cast to WPProject or extend the interface |
404 on all dynamic routes | Missing dynamicParams = true | Add export const dynamicParams = true to the route file |
| Build times out on Vercel | Too many pages in generateStaticParams | Reduce to 20 most recent, let rest generate on demand |
WordPress Admin Issues
| Issue | Fix |
|---|---|
| Locked out of wp-admin after URL change | Update siteurl and home in the WordPress database via phpMyAdmin in hPanel |
| White screen after editing functions.php | PHP syntax error. Use hPanel File Manager to revert the last change |
| Plugin update broke the site | Restore from Hostinger automatic backup (hPanel → Backups) |
| Media uploads failing | Check folder permissions — wp-content/uploads must be 755 |
CORS Debugging
# Check if CORS headers are present
curl -I -H "Origin: https://yourdomain.com" \
https://cms.yourdomain.com/wp-json/wp/v2/posts
# Look for this in the response:
# Access-Control-Allow-Origin: https://yourdomain.com
# If missing, add add_cors_headers() to functions.php (see Phase 0)When stuck, check the browser Network tab first. The actual error response from the WordPress API is almost always more informative than the React error message in the console.