N
HeadlessCoreHeadless Core
Back to Home

Troubleshooting

Common issues and how to fix them.

WordPress / GraphQL

GraphQL endpoint returns 404

Symptoms: http://localhost/headleespro/graphql not found

Fixes:

  1. Ensure WPGraphQL plugin is installed and activated
  2. Go to Settings → Permalinks and click Save (flushes rewrite rules)
  3. Verify Apache/nginx rewrite rules allow /graphql

GraphQL returns empty themeSettings

Symptoms: Next.js shows mock data even with WP running

Fixes:

  1. Activate HeadlessCore theme
  2. Check NEXT_PUBLIC_WORDPRESS_API_URL ends with /graphql
  3. Open browser DevTools → Network → verify GraphQL POST returns 200

CORS errors in browser

Symptoms: Access-Control-Allow-Origin error when fetching GraphQL from browser

Note: HeadlessCore fetches GraphQL server-side only. If you see CORS errors, you may be calling GraphQL from client components — move fetches to Server Components or API routes.

For client-side GraphQL (not recommended), install a CORS plugin or configure your web server.

Next.js / Frontend

Site shows mock data only

Symptoms: Homepage says "Local Mock Mode Active"

Fixes:

  1. Create nextjs-starter-kit/.env.local from .env.example
  2. Set NEXT_PUBLIC_WORDPRESS_API_URL=http://localhost/headleespro/graphql
  3. Restart npm run dev
  4. Ensure XAMPP/Apache is running

Build fails with TypeScript errors

cd nextjs-starter-kit
npm run build

Read the error file and line. Common causes:

  • Missing env vars (build should still pass with mock fallback)
  • Import errors after custom edits

Images not loading

Symptoms: Broken images from WordPress

Fixes:

  1. Add your WordPress host to next.config.ts → images.remotePatterns
  2. Set NEXT_PUBLIC_WORDPRESS_URL correctly
  3. Use SafeImage component (falls back to placeholder on error)

Wrong homepage layout

Symptoms: Expected blog but see demo showcase

Fix: Headless Core → Settings → Home Page Layout → choose mode → Save. Wait for revalidation or hard-refresh.

Revalidation / Cache

Content not updating after publish

Symptoms: Edited post in WP but Next.js shows old content

Checklist:

  1. headlesscore_nextjs_url in WP = your Next.js URL (no trailing slash issues)
  2. REVALIDATION_SECRET in .env.local matches WP admin Revalidation Secret
  3. WordPress can reach Next.js URL (firewall, localhost vs production)
  4. Test manually:
curl -X POST http://localhost:3000/api/revalidate \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_SECRET","path":"/blog","tag":"posts"}'

Local dev note: WordPress on XAMPP cannot POST to localhost:3000 if Next.js isn't running. Start npm run dev first.

401 on revalidation

Secret mismatch. Regenerate and sync:

openssl rand -base64 32

Set same value in WP admin and .env.local, restart Next.js.

Preview mode

Preview link shows 401

PREVIEW_SECRET in Next.js doesn't match WordPress Preview Secret.

Preview shows published content, not draft

  1. Set WORDPRESS_AUTH_TOKEN in .env.local (JWT from WPGraphQL login)
  2. Ensure WPGraphQL JWT Authentication plugin is active
  3. Verify draft mode banner appears (yellow bar at top)

Contact form

Form submits but no email

  1. Check WordPress admin_email in Settings → General
  2. Configure SMTP plugin if host blocks wp_mail()
  3. Check Headless Core → Contact Submissions — logs are always saved

Webhook not firing

  1. Set Contact Webhook URL in Headless Core settings
  2. Use Slack incoming webhook or Discord webhook URL
  3. Test with a manual POST to verify URL is valid

Shop / Products

Shop page shows mock products only

  1. Create items under Headless Core → Shop Products
  2. Set price meta field
  3. Publish products
  4. Verify GraphQL:
{ headlessProducts { nodes { title productPrice } } }

WooCommerce products not appearing

Install WPGraphQL for WooCommerce plugin. Shop page calls getShopProducts() as fallback when headlessProducts is empty.

Docker

docker compose up fails

  1. Ensure ports 8080/3306 are free
  2. Run docker compose down -v to reset volumes
  3. Check Docker Desktop is running (Windows/Mac)

Theme changes not reflected

Volume mount should map ./wp-content/themes/wp-headless-theme. Restart container after theme file changes.

CLI

Template not found

Run from HeadlessCore repository root, or:

npm run sync:template

Getting help

  1. Check Architecture for data flow
  2. Check Content Model for CPT/field reference
  3. Run npm test && npm run build to verify codebase health
  4. Check WP dashboard HeadlessCore Status widget for connection health