Troubleshooting

Common issues and solutions to help you resolve problems quickly.

API Connection Issues

GraphQL/JSON:API Not Responding

API endpoints return 404 or connection errors.

Possible Causes

• Incorrect API endpoint URL
• Site not fully provisioned
• Network connectivity issues
• API modules not enabled

Solutions

• Verify endpoint URLs -- Check that your environment variables match your site URL
• Test endpoints directly -- Visit https://your-site.decoupled.website/graphql in your browser
• Check site status -- Verify site is running in the decoupled.io dashboard

Quick Debug Commands

# Test GraphQL endpoint
curl -X POST https://your-site.decoupled.website/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name } } }"}'

# Test JSON:API endpoint
curl https://your-site.decoupled.website/jsonapi/node/article

# Check environment variable
echo $NEXT_PUBLIC_DRUPAL_BASE_URL

Build & Deployment Issues

Build Fails with API Errors

Next.js build process fails when fetching data.

Common Error Messages

Error: fetch failed
TypeError: Cannot read properties of undefined
GraphQL error: Field doesn't exist

Solutions

• Add error handling -- Wrap API calls in try-catch blocks
• Use fallback data -- Provide default values for missing data
• Validate environment variables -- Ensure all required env vars are set in build environment

Robust Error Handling Example

// Robust data fetching with error handling
export async function getStaticProps() {
  try {
    const articles = await fetchArticles();

    return {
      props: {
        articles: articles || [],
        error: null
      },
      revalidate: 300,
    }
  } catch (error) {
    console.error('Failed to fetch articles:', error);

    return {
      props: {
        articles: [],
        error: 'Failed to load content'
      },
      revalidate: 60, // Retry sooner on error
    }
  }
}

Performance Issues

Slow Page Load Times

Pages take too long to load or render.

Diagnosis Steps

• Check Network tab in DevTools
• Run Lighthouse audit
• Monitor API response times
• Check bundle size

Optimization Tips

• Enable ISR for static content
• Optimize images with Next.js Image
• Implement code splitting
• Use React.memo for expensive components

Performance Monitoring

// Add performance monitoring
export function reportWebVitals(metric) {
  if (metric.label === 'web-vital') {
    console.log(metric);

    // Send to analytics
    gtag('event', metric.name, {
      value: Math.round(metric.value),
      event_label: metric.id,
    });
  }
}

Common Error Messages

CORS Error

Error: Access to fetch at 'https://...' has been blocked by CORS policy

Solution: Ensure you're making requests from the correct domain or use server-side fetching.

GraphQL Schema Error

Error: Cannot query field "fieldName" on type "NodeArticle"

Solution: Check that the field exists in Drupal and is exposed in the GraphQL schema.

Environment Variable Missing

Error: TypeError: Cannot read properties of undefined (reading 'NEXT_PUBLIC_DRUPAL_BASE_URL')

Solution: Add NEXT_PUBLIC_DRUPAL_BASE_URL to your .env.local file.

Rate Limit Exceeded

Error: HTTP 429: Too Many Requests

Solution: Implement request caching or contact support for higher limits.

Getting Help

When to Contact Support

Self-Service First

• Check this troubleshooting guide
• Review API documentation
• Test with minimal reproduction
• Check system status page

Contact Support For

• Site provisioning issues
• Persistent API errors
• Performance problems
• Security concerns

Include This Information

When contacting support, provide:

• Site URL and environment
• Error messages and stack traces
• Steps to reproduce the issue
• Browser and version information