Troubleshooting

Common issues and their solutions. If you encounter problems, check this section first.

Common Issues

1. CORS Errors

Problem: CORS errors when accessing WooCommerce API

Solution:

• Ensure WooCommerce allows requests from your domain
• Check next.config.mjs for image domain configuration
• Use API routes as proxy (already configured in the project)
• Verify CORS headers in WooCommerce settings

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "your-store.com",
      },
      {
        protocol: "https",
        hostname: "*.your-store.com", // For subdomains
      },
    ],
  },
};

export default nextConfig;

2. Cart Token Not Persisting

Problem: Cart items disappear on page refresh

Solution:

• Check cookie settings (httpOnly, sameSite, path)
• Ensure cart token is being set in API responses
• Verify cookie domain matches your site domain
• Check browser console for cookie-related errors
• Ensure cookies are not being blocked by browser settings

// In API route response
response.cookies.set("cart_token", cartToken, {
  httpOnly: true,
  sameSite: "lax",
  path: "/",
  secure: process.env.NODE_ENV === "production" // HTTPS only in production
});

3. Authentication Failures

Problem: Login not working or users getting logged out

Solution:

• Verify WordPress REST API is enabled
• Check API credentials are correct in .env.local
• Ensure user has proper permissions in WordPress
• Check token expiration settings
• Verify JWT plugin is installed and configured (if using JWT)
• Check network tab for API request/response details

4. Product Images Not Loading

Problem: Images return 403 or don’t display // Images return 403 or don’t display with the given images return 403 or don’t display

Solution:

Add image domain to next.config.mjs:

images: { // Set images with the given images
  remotePatterns: [
    {
      protocol: "https",
      hostname: "your-store.com", // Set hostname with the given hostname
    },
    {
      protocol: "https",
      hostname: "*.your-store.com", // Set hostname with the given hostname
    },
  ],
}

Also check:

• Image URLs are accessible
• Images are not password protected
• WooCommerce image settings allow external access

5. Build Errors

Problem: Build fails with module not found or other errors

Solution:

# Clear Next.js cache
rm -rf .next

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Try building again
npm run build

6. API Rate Limiting

Problem: Too many requests to WooCommerce, getting rate limited

Solution:

• Implement request caching
• Use React Query or SWR for data fetching with caching
• Batch API requests when possible
• Debounce search and filter inputs
• Reduce unnecessary API calls

7. Environment Variables Not Loading

Problem: Environment variables are undefined

Solution:

• Ensure .env.local is in the root directory
• Restart the development server after changing environment variables
• Check variable names match exactly (case-sensitive)
• Verify no typos in variable names
• In production, ensure environment variables are set in your hosting provider

8. Middleware Not Working

Problem: Protected routes not redirecting to login

Solution:

• Verify middleware file is in src/ directory
• Check matcher patterns match your routes
• Ensure middleware is exported correctly
• Check browser console for middleware errors
• Verify cookies are being read correctly

9. Cart Not Updating

Problem: Cart operations not reflecting changes

Solution:

• Check cart token is being sent with requests
• Verify Store API is accessible
• Check browser network tab for API errors
• Ensure cart context is properly initialized
• Verify WooCommerce Store API is enabled

10. Slow Performance

Problem: Application is slow or unresponsive

Solution:

• Use Server Components for data fetching
• Implement proper caching strategies
• Optimize images with Next.js Image component
• Code split heavy components
• Reduce API calls with batching
• Use React.memo for expensive components

Debugging Tips

1. Check Network Tab

Inspect API requests and responses in browser DevTools:

• Open DevTools (F12)
• Go to Network tab
• Filter by XHR/Fetch
• Check request headers, body, and response
• Look for error status codes (4xx, 5xx)

2. Console Logs

Add logging in API routes and components:

// In API route
export async function GET(request) { // Get request with the given request
  console.log("API Request:", request.url); // Log API request with the given request url
  try {
    const data = await fetchData(); // Fetch data with the given fetch data
    console.log("API Response:", data); // Log API response with the given data
    return NextResponse.json(data);
  } catch (error) {
    console.error("API Error:", error); // Log API error with the given error
    return NextResponse.json({ error: error.message }, { status: 500 }); // Return next response with the given error message and status 500
  }
}

3. WooCommerce Logs

Check WooCommerce logs for backend errors:

• Go to WordPress Admin
• Navigate to WooCommerce → Status → Logs
• Check recent log files for errors
• Look for API-related errors

4. Next.js Logs

Check terminal output during development:

• Look for compilation errors
• Check for runtime errors
• Monitor API route logs
• Watch for memory warnings

5. Browser DevTools

Use browser DevTools for debugging:

• Console: Check for JavaScript errors
• Network: Inspect API requests
• Application: Check cookies and localStorage
• React DevTools: Inspect component state

Getting Help

If you’re still experiencing issues:

• Check WooCommerce REST API documentation
• Review Next.js App Router documentation
• Check project GitHub issues
• WooCommerce support forums
• Next.js Discord community

Common Error Messages

Prevention Tips

• Test Locally First: Always test changes locally before deploying
• Use Version Control: Commit changes frequently
• Read Error Messages: Error messages often contain the solution
• Keep Dependencies Updated: Regularly update packages
• Monitor Logs: Regularly check application logs

Tip: Most issues can be resolved by checking environment variables, restarting the dev server, and clearing browser cache.