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.io/graphql in browser

Check site status

Verify site is running in decoupled.io dashboard

Quick Debug Commands

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

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

# Check environment variables
echo $DRUPAL_GRAPHQL_URL
echo $DRUPAL_JSONAPI_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

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

Cannot query field "fieldName" on type "NodeArticle"

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

Environment Variable Missing

TypeError: Cannot read properties of undefined (reading 'DRUPAL_GRAPHQL_URL')

Solution: Add missing environment variables to your .env.local file

Rate Limit Exceeded

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:

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