---
title: "Troubleshooting"
description: "Common errors and how to fix them"
canonical_url: "https://wpnuxt.com/reference/troubleshooting"
---
# Troubleshooting

> Common errors and how to fix them

## Quick Diagnosis

Run `wpnuxi doctor` to automatically check your project for common issues:

```bash
npx wpnuxi doctor
```

This verifies your `.env` configuration, WordPress URL, GraphQL endpoint reachability, WPGraphQL introspection, and required dependencies. Fix any failing checks before investigating further.

<callout type="tip">

Use `npx wpnuxi info` to display your environment details (OS, Node.js, package versions, WordPress URL) — useful when reporting issues.

</callout>

---

## Connection Errors

### WordPress site not found - DNS lookup failed

```text
[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

```text
[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:**

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

---

### WordPress GraphQL endpoint timed out

```text
[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:**

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

---

### WordPress GraphQL endpoint returned HTTP error

```text
[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:**

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

---

## Authentication Errors

### Headless Login for WPGraphQL plugin not detected

```text
[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:**

1. Install the [Headless Login for WPGraphQL](https://github.com/AxeWP/wp-graphql-headless-login) plugin
2. Activate it in WordPress
3. Configure at least one provider (Password, Google, GitHub, etc.)
4. Run `pnpm dev:prepare` to download the updated schema

---

### Cannot validate GraphQL schema

```text
[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:**

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

---

## Build Errors

### Schema download failed (403 / introspection disabled)

```text
[WPNuxt] WordPress GraphQL endpoint returned HTTP 403.
```

or

```text
[WPNuxt] Failed to download GraphQL schema.
```

**Cause:** Public introspection is disabled on your WordPress GraphQL endpoint. WPNuxt needs introspection access at build time to download the schema and generate types.

**Solution:**

Set the `WPNUXT_SCHEMA_AUTH_TOKEN` environment variable to a valid authentication token:

```bash [.env]
WPNUXT_SCHEMA_AUTH_TOKEN=your-auth-token
```

This sends the token as a `Bearer` header during build-time schema operations. See [Securing Introspection](https://wpnuxt.com/getting-started/wordpress-setup#securing-introspection) for setup details.

Alternatively, set `downloadSchema: false` and commit a manually-downloaded `schema.graphql` to your repository.

---

### GraphQL document validation failed

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

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

**Solution:**

1. Run `pnpm dev:prepare` to refresh the schema
2. Check that all required WordPress plugins are installed:

  - WPGraphQL (required)
  - Headless Login for WPGraphQL (for auth)
  - WPGraphQL for ACF (if using ACF fields)
3. Verify your custom queries in `extend/queries/` are valid

---

### downloadSchema is set to false but no schema exists

```text
[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:**

1. Set `downloadSchema: true` in your config (recommended)
2. Or generate the schema file once and commit it: temporarily set `downloadSchema: true` (with WordPress reachable) and run `npx nuxi prepare` — WPNuxt writes `schema.graphql` to your project root. Avoid third-party download tools like `get-graphql-schema`; its output drops `implements` relationships between interfaces, which breaks block fragment validation.

---

## 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:

```bash
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:**

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

---

## Common Issues

### CORS Errors

```text
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:**

1. In WordPress, go to **GraphQL → Settings** and configure CORS:

  - Add your Nuxt development URL (e.g., `http://localhost:3000`) to allowed origins
2. Alternatively, proxy GraphQL requests through Nuxt using route rules:
```ts [nuxt.config.ts]
routeRules: {
  '/api/graphql/**': {
    proxy: 'https://your-wordpress.com/graphql/**'
  }
}
```
3. 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:**

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

---

### GraphQL Field Not Found

```text
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:**

1. Check `schema.graphql` in your project root to see available fields
2. If using ACF, install [WPGraphQL for ACF](https://github.com/wp-graphql/wpgraphql-acf) and enable "Show in GraphQL" for each field group
3. 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:**

1. Check post status in WordPress — ensure content is **Published**
2. In **GraphQL → Settings**, verify the content type is enabled
3. For custom post types, ensure the registration includes:
```php
'show_in_graphql' => true,
'graphql_single_name' => 'CustomPost',
'graphql_plural_name' => 'CustomPosts',
```

---

### SSG Build Failures

```text
[nitro] Error while prerendering /some-page
```

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

**Solution:**

1. Set `failOnError: false` in your prerender config to avoid failing the entire build:
```ts [nuxt.config.ts]
nitro: {
  prerender: {
    failOnError: false
  }
}
```
2. Verify WordPress is accessible from your build environment
3. Check the `WPNUXT_WORDPRESS_URL` environment variable is set correctly in CI
4. See the [SSG guide](https://wpnuxt.com/deploy/ssg) 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:**

1. If using `@wpnuxt/blocks`, add your WordPress domain to `imageDomains`:
```ts [nuxt.config.ts]
wpNuxtBlocks: {
  imageDomains: ['your-wordpress.com']
}
```
2. If using `@nuxt/image` standalone, add it to `image.domains`:
```ts [nuxt.config.ts]
image: {
  domains: ['your-wordpress.com']
}
```
3. 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:**

1. **Preferred:** Enable HTTPS on WordPress and update `wordpressUrl` to use `https://`
2. **Alternative:** Use proxy route rules so images are served from your Nuxt domain:
```ts [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:**

1. Verify `WPNUXT_WORDPRESS_URL` is set correctly in your production environment
2. 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)
3. Consider using an [image provider](https://wpnuxt.com/guide/images#image-providers) for production optimization

---

## Cache-Related Issues

### 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:**

1. Call `refresh()` in your component to force a fresh fetch:
```vue
<script setup>
const { data, refresh } = await usePosts()
</script>
```
2. Reduce `cache.maxAge` for content that updates frequently
3. 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:**

1. Ensure the preview request includes authentication (the auth token tells the server to bypass cache)
2. 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:**

1. Compare `wpNuxt.cache` settings between your development and production configs
2. In development, the cache may be shorter or disabled — check if production uses different `maxAge` or `swr` values
3. 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:

```ts [nuxt.config.ts]
wpNuxt: {
  debug: true
}
```

Or via environment variable:

```bash
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:

1. Check the [GitHub Issues](https://github.com/wpnuxt/wpnuxt/issues)
2. Search for similar problems
3. Open a new issue with:

  - WPNuxt version
  - Nuxt version
  - WordPress plugins installed
  - Full error message
  - Steps to reproduce


## Sitemap

See the full [sitemap](https://wpnuxt.com/sitemap.md) for all pages.