Troubleshooting Decision Tree
Visual decision tree for troubleshooting common issues.
Build Issues
Build Fails
├── TypeScript Errors?
│ ├── Yes → Check types, run `npx tsc --noEmit`
│ └── No → Continue
├── Module Not Found?
│ ├── Yes → Reinstall dependencies, check imports
│ └── No → Continue
├── Build Timeout?
│ ├── Yes → Increase Node memory, optimize build
│ └── No → Continue
└── Other → Check [Troubleshooting Guide](./TROUBLESHOOTING.md)
Runtime Errors
Runtime Error
├── Hydration Mismatch?
│ ├── Yes → Check server/client rendering, use 'use client'
│ └── No → Continue
├── "window is not defined"?
│ ├── Yes → Add browser check or move to client component
│ └── No → Continue
├── API Route Not Found?
│ ├── Yes → Check route file location, verify exports
│ └── No → Continue
└── Other → Check [Troubleshooting Guide](./TROUBLESHOOTING.md)
Performance Issues
Performance Problem
├── Slow Page Loads?
│ ├── Yes → Check bundle size, optimize images, enable caching
│ └── No → Continue
├── High Memory Usage?
│ ├── Yes → Check for leaks, optimize state, clear unused data
│ └── No → Continue
├── Slow API Responses?
│ ├── Yes → Enable caching, optimize queries, check network
│ └── No → Continue
└── Other → Check [Performance Guide](./PERFORMANCE.md)
Component Issues
Component Problem
├── Modal Not Closing?
│ ├── Yes → Check isOpen state, verify onClose handler
│ └── No → Continue
├── Tooltip Not Showing?
│ ├── Yes → Check z-index, verify trigger element
│ └── No → Continue
├── Form Validation Not Working?
│ ├── Yes → Check validation rules, verify form submission
│ └── No → Continue
└── Other → Check [Components Guide](./COMPONENTS.md)
Configuration Issues
Configuration Problem
├── Environment Variables Not Working?
│ ├── Yes → Check naming (NEXT_PUBLIC_), restart server
│ └── No → Continue
├── Feature Flags Not Working?
│ ├── Yes → Check configuration, verify environment variable
│ └── No → Continue
├── i18n Not Working?
│ ├── Yes → Check locale setting, verify translations
│ └── No → Continue
└── Other → Check [Configuration Guide](./CONFIGURATION.md)
Deployment Issues
Deployment Problem
├── Build Fails on Deployment?
│ ├── Yes → Check Node version, verify environment variables
│ └── No → Continue
├── Assets Not Loading?
│ ├── Yes → Check file paths, verify build output
│ └── No → Continue
├── PWA Not Working?
│ ├── Yes → Check manifest, verify Service Worker, check HTTPS
│ └── No → Continue
└── Other → Check [Deployment Guide](./DEPLOYMENT.md)
Quick Decision Flow
Issue Type?
- Build Issue → Build Troubleshooting
- Runtime Error → Runtime Troubleshooting
- Performance → Performance Troubleshooting
- Component → Component Troubleshooting
- Configuration → Configuration Troubleshooting
- Deployment → Deployment Troubleshooting
- Other → Full Troubleshooting Guide
Common Solutions
Clear Cache
rm -rf .next
npm run dev
Reinstall Dependencies
rm -rf node_modules package-lock.json
npm install
Check Types
npx tsc --noEmit
Check Build
npm run build
Check Linting
npm run lint
Still Stuck?
- Search Documentation: Documentation Index
- Check FAQ: FAQ
- Review Troubleshooting: Troubleshooting Guide
- Search Issues: GitHub Issues
- Ask for Help: Support Guide