Troubleshooting Guide

Common issues and their solutions.

Table of Contents

• Build Issues
• Runtime Errors
• Performance Problems
• Component Issues
• API Issues
• Configuration Problems
• Deployment Issues

Build Issues

Build Fails with TypeScript Errors

Problem: TypeScript compilation errors during build.

Solutions:

1. Check TypeScript version compatibility

   npm list typescript
   

2. Clear build cache

   rm -rf .next
   npm run build
   

3. Check for type errors

   npx tsc --noEmit
   

4. Update TypeScript

   npm install typescript@latest
   

Module Not Found Errors

Problem: Cannot find module errors.

Solutions:

1. Reinstall dependencies

   rm -rf node_modules package-lock.json
   npm install
   

2. Check import paths

   • Use @/ alias for imports
   • Verify file paths are correct

3. Clear Next.js cache

   rm -rf .next
   

Build Timeout

Problem: Build process times out.

Solutions:

1. Increase Node.js memory

   NODE_OPTIONS="--max-old-space-size=4096" npm run build
   

2. Check for large dependencies

   npm run analyze
   

3. Optimize bundle size

   • Remove unused dependencies
   • Use dynamic imports

Runtime Errors

Hydration Mismatch

Problem: React hydration errors.

Solutions:

1. Check for client-only code in server components

   'use client';
   // Component code
   

2. Use dynamic imports for client-only components

   import dynamic from 'next/dynamic';
   const ClientComponent = dynamic(() => import('./ClientComponent'), {
     ssr: false,
   });
   

3. Ensure consistent rendering

   • Check for Date/Time differences
   • Verify random values

"window is not defined" Error

Problem: Using browser APIs in server components.

Solutions:

1. Check if running in browser

   if (typeof window !== 'undefined') {
     // Browser code
   }
   

2. Use useEffect for browser APIs

   useEffect(() => {
     // Browser code
   }, []);
   

3. Move to client component

   'use client';
   

API Route Not Found

Problem: 404 errors for API routes.

Solutions:

1. Check route file location

   • Should be in app/api/[route]/route.ts

2. Verify export names

   export async function GET() {}
   export async function POST() {}
   

3. Check Next.js version

   • Ensure using App Router format

Performance Problems

Slow Page Loads

Problem: Pages load slowly.

Solutions:

1. Check bundle size

   npm run analyze
   

2. Optimize images

   • Use Next.js Image component
   • Convert to WebP/AVIF
   • Use appropriate sizes

3. Enable caching

   const data = await advancedCache.get('key', fetcher, {
     strategy: 'cache-first',
     ttl: 60000,
   });
   

4. Lazy load components

   import dynamic from 'next/dynamic';
   const HeavyComponent = dynamic(() => import('./HeavyComponent'));
   

High Memory Usage

Problem: Application uses too much memory.

Solutions:

1. Check for memory leaks

   • Use DevTools memory profiler
   • Check for event listeners

2. Optimize state management

   • Use local state when possible
   • Clear unused state

3. Monitor memory

   import { useMemory } from '@/hooks/useMemory';
   const { memory } = useMemory();
   

Slow API Responses

Problem: API calls are slow.

Solutions:

1. Enable caching

   const { data } = useDataFetch('/api/data', {
     cache: { strategy: 'cache-first', ttl: 60000 },
   });
   

2. Optimize API routes

   • Add response caching
   • Optimize database queries
   • Use connection pooling

3. Check network

   • Verify API endpoint
   • Check for rate limiting

Component Issues

Modal Not Closing

Problem: Modal doesn't close when expected.

Solutions:

1. Check isOpen state

   const [isOpen, setIsOpen] = useState(false);
   <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} />
   

2. Verify event handlers

   • Ensure onClose is called
   • Check for event propagation

3. Check for multiple modals

   • Ensure only one modal is open

Tooltip Not Showing

Problem: Tooltip doesn't appear.

Solutions:

1. Check z-index

   • Ensure tooltip has high z-index
   • Check for overlapping elements

2. Verify trigger element

   • Ensure element is interactive
   • Check for pointer-events

3. Check positioning

   • Verify viewport space
   • Check for overflow hidden

Form Validation Not Working

Problem: Form validation doesn't trigger.

Solutions:

1. Check validation rules

   validation: {
     email: { required: true, email: true },
   }
   

2. Verify form submission

   <form onSubmit={handleSubmit}>
   

3. Check error display

   {errors.email && <span>{errors.email}</span>}
   

API Issues

CORS Errors

Problem: Cross-origin request blocked.

Solutions:

1. Configure CORS in API route

   export async function GET() {
     return NextResponse.json(data, {
       headers: {
         'Access-Control-Allow-Origin': '*',
       },
     });
   }
   

2. Use Next.js rewrites

   // next.config.ts
   async rewrites() {
     return [
       {
         source: '/api/:path*',
         destination: 'https://api.example.com/:path*',
       },
     ];
   }
   

Rate Limiting

Problem: Too many requests error.

Solutions:

1. Check rate limit configuration

   const result = rateLimiter.check('user-id', 100, 60000);
   

2. Implement retry logic

   const { retry } = useRetry(fetchData, {
     maxRetries: 3,
     delay: 1000,
   });
   

3. Add request throttling

   const throttledFetch = throttle(fetchData, 1000);
   

API Timeout

Problem: API requests timeout.

Solutions:

1. Increase timeout

   const data = await fetchWithCache(url, {
     timeout: 30000,
   });
   

2. Add retry logic

   const { data } = useDataFetch(url, {
     retries: 3,
     retryDelay: 1000,
   });
   

3. Check API endpoint

   • Verify endpoint is accessible
   • Check network connectivity

Configuration Problems

Environment Variables Not Working

Problem: Environment variables not accessible.

Solutions:

1. Check variable naming

   • Must start with NEXT_PUBLIC_ for client
   • Restart dev server after changes

2. Verify file location

   • Should be .env.local in root
   • Check .gitignore

3. Access in code

   process.env.NEXT_PUBLIC_SITE_URL
   

Feature Flags Not Working

Problem: Feature flags don't toggle.

Solutions:

1. Check configuration

   export const featureFlags = {
     myFeature: process.env.NEXT_PUBLIC_MY_FEATURE === 'true',
   };
   

2. Verify hook usage

   const enabled = useFeatureFlag('myFeature');
   

3. Check environment variable

   • Ensure variable is set
   • Restart server

i18n Not Working

Problem: Translations not showing.

Solutions:

1. Check locale setting

   i18n.setLocale('de');
   

2. Verify translations exist

   i18n.addTranslations('de', {
     common: { loading: 'Lädt...' },
   });
   

3. Check hook usage

   const { t } = useI18n();
   const text = t('common.loading');
   

Deployment Issues

Build Fails on Deployment

Problem: Build fails in CI/CD.

Solutions:

1. Check Node.js version

   • Ensure version 18+
   • Set in CI/CD config

2. Verify environment variables

   • Set in deployment platform
   • Check variable names

3. Check build logs

   • Review error messages
   • Check for missing dependencies

Assets Not Loading

Problem: Static assets return 404.

Solutions:

1. Check file paths

   • Use / for public files
   • Verify file exists

2. Check Next.js config

   // next.config.ts
   assetPrefix: process.env.NODE_ENV === 'production' ? '/prefix' : '',
   

3. Verify build output

   • Check .next/static
   • Verify asset paths

PWA Not Working

Problem: PWA features not working.

Solutions:

1. Check manifest

   • Verify public/manifest.json
   • Check file paths

2. Verify Service Worker

   • Check public/sw.js
   • Verify registration

3. Check HTTPS

   • PWA requires HTTPS
   • Verify SSL certificate

Getting More Help

Still Having Issues?

1. Check Documentation

   • Review relevant guides
   • Check API documentation

2. Search Issues

   • Check GitHub issues
   • Search for similar problems

3. Create Issue

   • Provide error details
   • Include reproduction steps
   • Add environment info

Useful Commands

# Clear all caches
rm -rf .next node_modules package-lock.json
npm install

# Check for errors
npm run lint
npx tsc --noEmit

# Analyze bundle
npm run analyze

# Test build
npm run build

Debug Mode

Enable debug logging:

// In development
if (process.env.NODE_ENV === 'development') {
  console.log('Debug info');
}

Common Error Messages

"Cannot read property of undefined"

Solution: Add null checks

if (data && data.property) {
  // Use data.property
}

"Maximum update depth exceeded"

Solution: Check for infinite loops in useEffect

useEffect(() => {
  // Ensure dependencies are correct
}, [dependency]);

"Text content does not match"

Solution: Check for hydration mismatches

• Ensure server and client render same content
• Use suppressHydrationWarning if needed