Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
Common issues and their solutions when developing or deploying the web app. For the full web app overview, see Web App Overview.
| Issue |
Cause |
Solution |
FATAL ERROR: heap out of memory |
Large build exceeds Node.js memory |
Set NODE_OPTIONS="--max-old-space-size=4096" |
| TypeScript errors on build |
Type mismatches |
Run npx tsc --noEmit to check types |
| Missing module errors |
Stale node_modules |
Delete node_modules and npm install |
| Tailwind classes not working |
Purge config issue |
Check tailwind.config.ts content paths |
| Issue |
Cause |
Solution |
NEXT_PUBLIC_* undefined at runtime |
Not set before build |
Rebuild after adding env vars |
NEXTAUTH_URL mismatch |
URL doesn't match deployment |
Set to actual deployment URL |
| Stripe key errors |
Wrong key type (test vs live) |
Check environment matches key type |
| Issue |
Cause |
Solution |
| Token expired errors |
JWT not refreshing |
Check NextAuth JWT callback in server/auth.ts |
| OAuth redirect mismatch |
Callback URL misconfigured |
Add URL to Google/Facebook console |
CSRF token mismatch |
Domain/cookie issues |
Check NEXTAUTH_URL matches domain |
| Extension token not working |
Cookie not set |
Check extension cookie flag |
| Issue |
Cause |
Solution |
| Hydration mismatch |
Server/client render mismatch |
Check for browser-only code in SSR components |
| CORS errors |
Backend not allowing origin |
Check Django CORS settings |
| API 429 errors |
Rate limited |
Check plan limits, implement backoff |
| Slow initial page load |
Large bundle |
Check bundle size, implement code splitting |
| Issue |
Cause |
Solution |
| ECS task failing to start |
Health check failure |
Check CloudWatch logs, verify port 3001 |
| Docker build timeout in CI |
Large dependencies |
Increase timeout, check network |
| ECR push denied |
IAM permissions |
Check OIDC role permissions |
| Date |
Author |
Change |
| 2026-01-30 |
Admin |
Initial creation |
Prev: Web App - Deployment | Next: Web App - Humanizer Feature | Up: WalterWrites