Skip to main content

Troubleshooting

Solutions to common FlatWP issues and error messages.

Installation Issues​

Node.js Version Error​

Error: "The engine 'node' is incompatible with this module"

Cause: Using Node.js version older than 20.0.0

Solution:

# Check current version
node --version

# Update Node.js
# Using nvm
nvm install 20
nvm use 20

# Or download from nodejs.org

pnpm Install Fails​

Error: "Command failed: pnpm install"

Solutions:

  1. Update pnpm:

    npm install -g pnpm@latest

  2. Clear cache and retry:

    pnpm store prune
    pnpm install

  3. Delete node_modules and retry:

    rm -rf node_modules pnpm-lock.yaml
    pnpm install

Port Already in Use​

Error: "Port 3010 is already in use"

Solutions:

  1. Change port in package.json:

    "dev": "next dev -p 3011"

  2. Kill process using port:

    # macOS/Linux
    lsof -ti:3010 | xargs kill

    # Windows
    netstat -ano | findstr :3010
    taskkill /PID <PID> /F

WordPress Connection Issues​

GraphQL Endpoint Not Found​

Error: "Failed to fetch from WordPress GraphQL endpoint"

Checklist:

  • WPGraphQL plugin is installed and activated
  • WordPress site is accessible
  • NEXT_PUBLIC_WORDPRESS_API_URL is correct in .env.local
  • URL includes /graphql at the end
  • No typos in environment variable name

Test endpoint:

curl https://your-wordpress-site.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{__typename}"}'

Expected response:

{"data":{"__typename":"RootQuery"}}

CORS Errors​

Error: "Access-Control-Allow-Origin header is not present"

Solution: The FlatWP companion plugin handles CORS automatically.

If error persists:

  1. Verify FlatWP plugin is activated
  2. Check Next.js URL in WordPress plugin settings
  3. Clear browser cache
  4. Try in incognito mode

WPGraphQL Plugin Not Working​

Problem: GraphQL endpoint returns 404

Solutions:

  1. Verify plugin activation:

    • Go to Plugins in WordPress
    • Ensure "WPGraphQL" shows as "Active"

  2. Flush permalinks:

    • Go to Settings → Permalinks
    • Click Save Changes (don't change anything)
    • This refreshes WordPress rewrite rules

  3. Check .htaccess:

    • Ensure file is writable
    • WordPress can update it automatically

GraphQL & Type Generation Issues​

Types Not Generating​

Error: "Cannot find module '@/graphql/generated'"

Solutions:

  1. Run code generation:

    pnpm graphql:codegen

  2. Check WordPress is accessible:

    curl https://your-wordpress-site.com/graphql

  3. Verify environment variable:

    echo $NEXT_PUBLIC_WORDPRESS_API_URL

  4. Check for errors in codegen output:

    • Look for connection errors
    • Check for invalid GraphQL schema

GraphQL Query Errors​

Error: "Cannot query field 'X' on type 'Y'"

Cause: Field doesn't exist in WordPress GraphQL schema

Solutions:

  1. Check field exists:

    • Open GraphiQL: https://your-site.com/graphql
    • Explore schema in Documentation Explorer

  2. Install required plugin:

    • Some fields require specific plugins
    • Example: SEO fields require WPGraphQL SEO

  3. Regenerate types:

    pnpm graphql:codegen

Outdated Types​

Problem: TypeScript errors after WordPress changes

Solution: Regenerate types after schema changes:

pnpm graphql:codegen

Automate in development:

pnpm graphql:codegen --watch

ISR & Revalidation Issues​

Pages Not Updating​

Problem: WordPress changes don't appear on Next.js site

Checklist:

  • FlatWP plugin shows "Connected" status
  • Webhooks are enabled in plugin settings
  • REVALIDATION_SECRET matches in both places
  • Next.js site URL is correct in WordPress

Test webhook manually:

curl -X POST https://your-site.com/api/revalidate \
  -H "Content-Type: application/json" \
  -d '{"secret":"your-revalidation-secret","paths":["/"]}'

Expected response:

{"revalidated":true,"paths":["/"]}

Webhook Returns 401​

Error: "Invalid revalidation secret"

Cause: Secrets don't match

Solution:

  1. Check REVALIDATION_SECRET in .env.local
  2. Check secret in WordPress Settings → FlatWP
  3. Ensure no extra spaces or characters
  4. Copy-paste to avoid typos

Stale Content After Revalidation​

Problem: Content still old after triggering revalidation

Explanation: ISR uses stale-while-revalidate:

  1. First visitor after change sees old content
  2. Regeneration happens in background
  3. Next visitor sees new content

Solution: This is expected behavior. For instant updates, consider:

  • Using shorter revalidate time
  • Implementing SSR for that page
  • Warming cache after revalidation

Build & Deployment Issues​

Build Timeout​

Error: "Build exceeded maximum time limit"

Causes:

  • Too many pages in generateStaticParams()
  • Large images not optimized
  • Slow WordPress API responses

Solutions:

  1. Limit static generation in development:

    export async function generateStaticParams() {
      const limit = process.env.NODE_ENV === 'production' ? 1000 : 10;
      const posts = await getAllPosts({ limit });
      return posts.map(post => ({ slug: post.slug }));
    }

  2. Enable dynamic params:

    export const dynamicParams = true;

  3. Optimize images:

    • Compress images before uploading to WordPress
    • Use WebP format
    • Enable WordPress image optimization plugins

Out of Memory Error​

Error: "JavaScript heap out of memory"

Solution: Increase Node.js memory:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

Build Succeeds But Site Broken​

Problem: Build completes but pages don't work

Check:

  1. Environment variables set in deployment:

    • Verify all required variables
    • Check for typos

  2. API endpoint accessible:

    • Test from production environment
    • Check firewall rules

  3. Check deployment logs:

    • Look for runtime errors
    • Check for missing environment variables

Preview Mode Issues​

Preview Not Working​

Problem: Preview links show published content

Checklist:

  • PREVIEW_SECRET is set
  • Secret matches in WordPress
  • User is logged into WordPress
  • Preview mode is enabled in plugin

Test preview endpoint:

curl https://your-site.com/api/preview?secret=your-preview-secret&id=123

Preview Shows 404​

Error: Preview page not found

Causes:

  • Post ID doesn't exist
  • Post is in trash
  • WordPress API not accessible

Solution: Check post exists and is in draft/pending status

Image Optimization Issues​

Images Not Loading​

Problem: Images show broken or don't load

Checklist:

  • WordPress URL is accessible
  • Images exist in WordPress media library
  • sourceUrl field is in GraphQL query
  • CORS allows image loading

Check image URL:

console.log('Image URL:', post.featuredImage?.node?.sourceUrl);

Images Not Optimized​

Problem: Images load slowly or in wrong format

Solution: Use Next.js Image component:

import Image from 'next/image';

<Image
  src={post.featuredImage.node.sourceUrl}
  alt={post.featuredImage.node.altText}
  width={800}
  height={600}
  quality={85}
/>

Configure image domains in next.config.ts:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-wordpress-site.com',
      },
    ],
  },
};

Performance Issues​

Slow Page Loads​

Possible Causes:

  1. Large un-optimized images
  2. Not using ISR (fetching on every request)
  3. Slow WordPress API
  4. Not using edge caching

Solutions:

  1. Enable ISR:

    export const revalidate = 300; // 5 minutes

  2. Optimize images:

    • Use Next.js Image component
    • Compress images in WordPress
    • Use WebP format

  3. Cache WordPress responses:

    • Install WordPress caching plugin
    • Use Redis for object caching
    • Enable CDN

  4. Use edge deployment:

    • Deploy to Vercel/Netlify
    • Enable edge caching
    • Use edge functions

High Memory Usage​

Problem: Next.js uses too much memory

Solutions:

  1. Limit concurrent builds:

    export NEXT_BUILD_WORKERS=2

  2. Reduce bundle size:

    • Use dynamic imports
    • Tree-shake unused code
    • Analyze bundle: pnpm build --analyze

Development Issues​

Hot Reload Not Working​

Problem: Changes not reflecting in browser

Solutions:

  1. Restart dev server:

    # Stop with Ctrl+C
    pnpm dev

  2. Clear Next.js cache:

    rm -rf .next
    pnpm dev

  3. Check file watching limits (Linux):

    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
    sudo sysctl -p

TypeScript Errors​

Problem: Type errors in IDE

Solutions:

  1. Restart TypeScript server:

    • VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

  2. Regenerate types:

    pnpm graphql:codegen

  3. Check TypeScript version:

    pnpm list typescript

Getting Help​

If you're still experiencing issues:

Before Asking for Help​

  1. Check error messages carefully

    • Read the full error, not just the first line
    • Search for the error message online

  2. Check existing issues:

  3. Gather information:

    • Node.js version: node --version
    • pnpm version: pnpm --version
    • Next.js version: Check package.json
    • WordPress version
    • Error logs from console

Get Support​

  1. Community Support:

  2. Report Bugs:

  3. Documentation:

    • Search these docs
    • Check Next.js docs
    • Check WordPress docs

Common Error Messages​

"Module not found"​

Cause: Missing dependency or incorrect import path

Solutions:

  1. Install dependency: pnpm add <package>
  2. Check import path is correct
  3. Ensure file exists at import path

"Hydration failed"​

Cause: Server HTML doesn't match client HTML

Common Causes:

  • Using localStorage in server components
  • Conditional rendering based on browser APIs
  • Incorrect nesting (e.g., <p> inside <p>)

Solution: Move client-side logic to client components:

'use client';

import { useEffect, useState } from 'react';

export function ClientComponent() {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;

  // Client-side logic here
}

"ECONNREFUSED"​

Cause: Cannot connect to service

Check:

  • Service is running
  • Correct host and port
  • Firewall not blocking
  • Network connectivity

See Also​