Reference

Troubleshooting

Common errors and how to fix them

Connection Errors

WordPress site not found - DNS lookup failed

[WPNuxt] WordPress site not found - DNS lookup failed.

URL: https://wordpress.exmaple.com/graphql

The domain could not be resolved. Please check:
- The URL is spelled correctly (no typos)
- The domain exists and is properly configured
- Your network connection is working

Cause: The WordPress URL in your configuration has a typo or the domain doesn't exist.

Solution: Check your wpNuxt.wordpressUrl in nuxt.config.ts or WPNUXT_WORDPRESS_URL environment variable.

Connection refused to WordPress site

[WPNuxt] Connection refused to WordPress site.

URL: https://wordpress.example.com/graphql

The server is not accepting connections. Check if the WordPress site is running.

Cause: The WordPress server is down or not accepting connections on the specified port.

Solution:

Verify the WordPress site is running
Check if a firewall is blocking the connection
Ensure the URL uses the correct protocol (http vs https)

WordPress GraphQL endpoint timed out

[WPNuxt] WordPress GraphQL endpoint timed out after 10 seconds.

URL: https://wordpress.example.com/graphql

The server did not respond in time. Check if the WordPress site is accessible.

Cause: The WordPress server is too slow or unreachable.

Solution:

Check if the WordPress site is accessible in a browser
Verify your network connection
Check if the WordPress server is under heavy load

WordPress GraphQL endpoint returned HTTP error

[WPNuxt] WordPress GraphQL endpoint returned HTTP 404.

URL: https://wordpress.example.com/graphql

Possible causes:
- The WordPress site is down or unreachable
- WPGraphQL plugin is not installed or activated
- The GraphQL endpoint path is incorrect (default: /graphql)

Cause: The GraphQL endpoint is not available at the specified URL.

Solution:

Install and activate the WPGraphQL plugin
Check if the endpoint path is correct (default is /graphql)
Try accessing https://your-wordpress.com/graphql in a browser - you should see the GraphQL IDE

Authentication Errors

[WPNuxt Auth] Headless Login for WPGraphQL plugin not detected.

The @wpnuxt/auth module requires this WordPress plugin for authentication.
Your WordPress GraphQL schema is missing the required 'login' mutation.

To fix this:
1. Install the plugin: https://github.com/AxeWP/wp-graphql-headless-login
2. Configure at least one authentication provider in WordPress
3. Run 'pnpm dev:prepare' to refresh the GraphQL schema

Cause: The @wpnuxt/auth module requires the "Headless Login for WPGraphQL" plugin, but it's not installed or activated.

Solution:

Install the Headless Login for WPGraphQL plugin
Activate it in WordPress
Configure at least one provider (Password, Google, GitHub, etc.)
Run pnpm dev:prepare to download the updated schema

Cannot validate GraphQL schema

[WPNuxt Auth] Cannot validate GraphQL schema.

The schema file does not exist or is empty. Run 'pnpm dev:prepare' first.

Cause: The schema.graphql file doesn't exist or couldn't be read.

Solution:

Run pnpm dev:prepare to download the schema
Ensure downloadSchema: true in your config (this is the default)
Check that your WordPress URL is correct and accessible

Build Errors

GraphQL document validation failed

[nuxt-graphql-middleware] ERROR
GraphQL document validation failed.

Cause: Your GraphQL queries reference types or fields that don't exist in the schema.

Solution:

Run pnpm dev:prepare to refresh the schema
Check that all required WordPress plugins are installed:
- WPGraphQL (required)
- Headless Login for WPGraphQL (for auth)
- WPGraphQL for ACF (if using ACF fields)
Verify your custom queries in extend/queries/ are valid

downloadSchema is set to false but no schema exists

[nuxt-graphql-middleware] ERROR
"downloadSchema" is set to false but no schema exists at ./schema.graphql

Cause: The schema file doesn't exist and automatic download is disabled.

Solution:

Set downloadSchema: true in your config (recommended)

Or manually download the schema:

npx get-graphql-schema https://your-wordpress.com/graphql > schema.graphql

Runtime Errors

User data disappears after page refresh

Cause: The authentication token exists but user data wasn't persisted.

Solution: This was fixed in a previous release. Update to the latest version:

pnpm update @wpnuxt/auth

OAuth callback error: Invalid state

Cause: The OAuth state parameter doesn't match, possibly due to session timeout or CSRF protection.

Solution:

Try logging in again
Ensure cookies are enabled in the browser
Check that your OAuth callback URL is correctly configured in WordPress

Common Issues

CORS Errors

Access to fetch at 'https://wordpress.example.com/graphql' has been blocked by CORS policy

Cause: WordPress and Nuxt are on different domains or ports, and WordPress isn't configured to allow cross-origin requests.

Solution:

In WordPress, go to GraphQL → Settings and configure CORS:
- Add your Nuxt development URL (e.g., http://localhost:3000) to allowed origins

Alternatively, proxy GraphQL requests through Nuxt using route rules:

nuxt.config.ts

routeRules: {
  '/api/graphql/**': {
    proxy: 'https://your-wordpress.com/graphql/**'
  }
}

In local development, this is common when WordPress runs on a different port — CORS settings in WPGraphQL typically resolve it

CORS with authentication (`@wpnuxt/auth`)

When using @wpnuxt/auth, the browser sends cookies with GraphQL requests. This requires additional CORS configuration on WordPress:

WordPress must respond with Access-Control-Allow-Credentials: true
The Access-Control-Allow-Origin header must be a specific origin (e.g., http://localhost:3000), not the wildcard * — browsers reject credentialed requests with a wildcard origin
Configure both of these in GraphQL → Settings → CORS in WordPress Admin

WordPress Permalink Structure

Symptom: URI-based queries (usePostByUri, useNodeByUri) return null even for published content.

Cause: WordPress is set to "Plain" permalinks (?p=123), which don't generate URI paths.

Solution:

In WordPress Admin, go to Settings → Permalinks
Select Post name (/%postname%/) or any "pretty" permalink structure
Click Save Changes
Run pnpm dev:prepare to refresh the schema

GraphQL Field Not Found

Cannot query field "customField" on type "Post"

Cause: Your custom query references a field that doesn't exist in the GraphQL schema. This happens when:

ACF fields aren't exposed to GraphQL
A required plugin isn't installed
The field name doesn't match the schema

Solution:

Check schema.graphql in your project root to see available fields
If using ACF, install WPGraphQL for ACF and enable "Show in GraphQL" for each field group
Run pnpm dev:prepare to refresh the schema after installing plugins

Empty Data / Null Responses

Symptom: Composables return null or empty arrays for content that exists in WordPress.

Cause: The content isn't visible via GraphQL. Common reasons:

Posts are in Draft or Private status
The content type isn't exposed in WPGraphQL settings
Custom post types need to be registered with show_in_graphql => true

Solution:

Check post status in WordPress — ensure content is Published
In GraphQL → Settings, verify the content type is enabled

For custom post types, ensure the registration includes:

'show_in_graphql' => true,
'graphql_single_name' => 'CustomPost',
'graphql_plural_name' => 'CustomPosts',

SSG Build Failures

[nitro] Error while prerendering /some-page

Cause: A network error occurred during static generation — WordPress was unreachable during the build.

Solution:

Set failOnError: false in your prerender config to avoid failing the entire build:
nuxt.config.ts
```
nitro: {
  prerender: {
    failOnError: false
  }
}
```
Verify WordPress is accessible from your build environment
Check the WPNUXT_WORDPRESS_URL environment variable is set correctly in CI
See the SSG guide for CI/CD configuration details

Image and Media Issues

Images not loading from WordPress

Symptom: Images from WordPress return 404 or show as broken.

Cause: The image domain isn't configured for <NuxtImg>, or WordPress blocks hotlinking from other domains.

Solution:

If using @wpnuxt/blocks, add your WordPress domain to imageDomains:
nuxt.config.ts
```
wpNuxtBlocks: {
  imageDomains: ['your-wordpress.com']
}
```
If using @nuxt/image standalone, add it to image.domains:
nuxt.config.ts
```
image: {
  domains: ['your-wordpress.com']
}
```
Check the browser console for blocked requests — security plugins on WordPress may prevent hotlinking

Mixed content errors (HTTPS/HTTP)

Symptom: Browser console shows "Mixed Content: The page was loaded over HTTPS, but requested an insecure image".

Cause: Your Nuxt site is served over HTTPS but WordPress image URLs use HTTP.

Solution:

Preferred: Enable HTTPS on WordPress and update wordpressUrl to use https://

Alternative: Use proxy route rules so images are served from your Nuxt domain:

nuxt.config.ts

routeRules: {
  '/wp-content/**': {
    proxy: 'https://your-wordpress.com/wp-content/**'
  }
}

Images broken after deploy

Symptom: Images work in local development but break in production.

Cause: The production environment can't reach WordPress image URLs, or route rules behave differently between dev and production.

Solution:

Verify WPNUXT_WORDPRESS_URL is set correctly in your production environment
If using proxy route rules, confirm your hosting platform supports them (Vercel, Netlify, and Node.js hosting all support route rules; static hosting may not)
Consider using an image provider for production optimization

Stale content after WordPress update

Symptom: Updated content in WordPress doesn't appear on the Nuxt site.

Cause: The server cache serves content until maxAge expires. With SWR enabled (the default), the first request after expiry triggers a background revalidation — so the request after that one gets fresh data.

Solution:

Call refresh() in your component to force a fresh fetch:

<script setup>
const { data, refresh } = await usePosts()
</script>

Reduce cache.maxAge for content that updates frequently
For immediate updates, consider implementing a WordPress webhook that clears the Nuxt cache on publish

Preview mode showing cached content

Symptom: WordPress preview shows the old version of content instead of the draft.

Cause: Authenticated preview requests should bypass the server cache, but client-side caching may still serve stale data.

Solution:

Ensure the preview request includes authentication (the auth token tells the server to bypass cache)
Use refresh() to force a fresh fetch when entering preview mode

Different content in dev vs production

Symptom: Content appears correctly in development but differs in production.

Cause: Different cache configurations between environments, or the production build used stale cached data.

Solution:

Compare wpNuxt.cache settings between your development and production configs
In development, the cache may be shorter or disabled — check if production uses different maxAge or swr values
After a fresh deploy, the first request populates the cache — subsequent requests serve cached content until maxAge expires

Debug Mode

Enable debug mode to get more detailed logs:

nuxt.config.ts

wpNuxt: {
  debug: true
}

Or via environment variable:

WPNUXT_DEBUG=true pnpm dev

Debug mode shows:

Query merging details
Endpoint validation status
Module loading times
Cache configuration

Getting Help

If you're still having issues:

Check the GitHub Issues
Search for similar problems
Open a new issue with:
- WPNuxt version
- Nuxt version
- WordPress plugins installed
- Full error message
- Steps to reproduce

Edit this pageorReport an issue

Composables

Composables API reference

Block Components

Reference for all included Gutenberg block components