Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
This page covers troubleshooting for local development environment issues specific to the WWAI (Walter) project. The WWAI frontend is a Next.js application that communicates with a Django backend. Most environment issues fall into one of these categories: Node.js/npm problems, missing or misconfigured environment variables, NextAuth/OAuth failures, build errors, Docker problems, Git/Husky issues, or network/port conflicts.
Before diving into individual issues, verify your .env.local file contains at least these variables. This is the bare minimum to get the app running locally:
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_ENVIRONMENT=local
NEXTAUTH_SECRET=any-random-string-for-dev
NEXTAUTH_URL=http://localhost:3000
WALTER_INTERNAL_KEY=your-internal-key
The .env.local file must be placed in the project root (the same directory as package.json).
nvm use 20
nvm install 20.9.0
nvm use 20.9.0
node --version -- it should output v20.9.0.npm install exits with errors such as ERESOLVE, EACCES, network timeouts, or corrupted package cache messages.node_modules from a different Node version.npm cache clean --force
rm -rf node_modules package-lock.json
npm install
npm cache clean --force
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install
npm install prints WARN lines about unmet peer dependencies.--force or --legacy-peer-deps unless explicitly instructed by a team lead. Using those flags can install incompatible dependency versions and cause subtle runtime bugs.undefined. The app behaves as if no .env.local file exists..env.local file is not in the project root directory (the directory containing package.json). Next.js only reads .env.local from the project root..env.local to the same directory as package.json. Verify with:ls -la .env.local package.json
NEXT_PUBLIC_* variable works on the server but is undefined in client-side (browser) code.NEXT_PUBLIC_* variables are baked into the JavaScript bundle at build time. They are statically replaced during the build process. Changing them after the build has no effect on client code.npm run dev. The dev server re-reads environment variables on startup.npm run build. Changing them after the build requires a full rebuild.NEXT_PUBLIC_ prefix) are read at runtime. Next.js does not validate their presence at build time..env.local and restart the dev server. For production, ensure the variable is set in the deployment environment (e.g., Vercel, Docker, CI/CD).Invalid callback URL errors.NEXTAUTH_URL must exactly match the URL where the application is accessed in the browser. Any mismatch (wrong port, wrong protocol, trailing slash differences) causes NextAuth to reject requests.NEXTAUTH_URL to the exact URL you use in the browser:# Local development
NEXTAUTH_URL=http://localhost:3000
# If using a different port
NEXTAUTH_URL=http://localhost:3001
NEXTAUTH_SECRET is required for signing/encrypting session tokens. Without it, NextAuth cannot create or validate sessions..env.local:openssl rand -base64 32
.env.local:NEXTAUTH_SECRET=<paste-generated-value-here>
NEXTAUTH_SECRET=my-dev-secret), but a proper random value is recommended.undefined/api/... or similar malformed URLs. The application is effectively non-functional.NEXT_PUBLIC_BACKEND_URL is the base URL for all backend API requests. Without it, every fetch/axios call constructs an invalid URL..env.local:NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
.env.local. Contact the team lead if you need access to shared development credentials..env.local. Use Stripe test-mode keys for local development. Contact the team lead for shared test credentials.WALTER_INTERNAL_KEY is sent as the X-Walter-Internal-Key HTTP header to authenticate server-to-server requests. The backend rejects requests without a valid key..env.local:WALTER_INTERNAL_KEY=your-internal-key
http://localhost:3000/api/auth/callback/google
http://localhost:3000/api/auth/callback/facebook
http://localhost:3001/api/auth/callback/google).NEXTAUTH_URL does not match the actual URL being accessed in the browser. NextAuth uses this value to validate CSRF tokens.NEXTAUTH_URL in .env.local exactly matches the browser URL:NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET is either not set or has changed between server restarts. When the secret changes, all existing session tokens become invalid.NEXTAUTH_SECRET is set in .env.local and remains consistent across restarts. Do not regenerate it unless you intend to invalidate all sessions.RefreshAccessTokenError. The user may be logged out unexpectedly.POST /api/user/refresh/./api/user/refresh/ endpoint is functional. Test directly with curl:curl -X POST http://localhost:8000/api/user/refresh/ \
-H "Content-Type: application/json" \
-d '{"refresh": "<your-refresh-token>"}'
npm run build crashes with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory.NODE_OPTIONS="--max-old-space-size=4096" npm run build
$env:NODE_OPTIONS="--max-old-space-size=4096"; npm run build
.env.local:NODE_OPTIONS=--max-old-space-size=4096
.next directory contains cached build artifacts that have become stale or corrupted..next directory and restart:rm -rf .next && npm run dev
Remove-Item -Recurse -Force .next; npm run dev
next dev --turbopack) crashes, shows incorrect output, or fails to compile certain modules.npx next dev
Hydration failed because the initial UI does not match what was rendered on the server or similar React hydration errors."use client" directive."use client" as the first line.useEffect to render dates only on the client side, or use a consistent formatting library with explicit timezone handling.node:20-alpine as builder).ECONNREFUSED or timeout errors, even though the backend is running on the host machine.localhost inside a Docker container refers to the container itself, not the host machine. NEXT_PUBLIC_BACKEND_URL=http://localhost:8000 does not work from within Docker.http://host.docker.internal:8000--network="host" flag or the host's actual IP address.node_modules.npm run prepare
.husky/ directory exists in the project root and contains hook files (e.g., pre-commit).git commit is rejected with formatting or linting errors. The error output mentions lint-staged or prettier.lint-staged on staged files, which applies Prettier formatting checks. If staged files do not match Prettier's formatting rules, the commit is rejected.npx prettier --write <file-path>
npx prettier --write .
git add <file-path>) and commit again.git push or git pull fails with Permission denied (publickey) or Could not read from remote repository.ssh -T git@github.com
ssh-keygen -t ed25519 -C "your-email@example.com"
~/.ssh/id_ed25519.pub) to GitHub: Settings > SSH and GPG keys > New SSH key.eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
npm run dev fails with Error: listen EADDRINUSE: address already in use :::3000.lsof -i :3000
kill -9 <PID>
netstat -ano | findstr :3000
taskkill /PID <PID> /F
PORT=3001 npm run dev
NEXTAUTH_URL to match:NEXTAUTH_URL=http://localhost:3001
UNABLE_TO_VERIFY_LEAF_SIGNATURE, CERT_HAS_EXPIRED, or similar SSL errors.NODE_TLS_REJECT_UNAUTHORIZED=0 npm run dev
Access to fetch at 'http://localhost:8000/...' from origin 'http://localhost:3000' has been blocked by CORS policy.http://localhost:3000 in its CORS_ALLOWED_ORIGINS setting.http://localhost:3000 to the CORS_ALLOWED_ORIGINS list.django-cors-headers and the middleware is properly configured.NEXT_PUBLIC_BACKEND_URL points to the wrong address.NEXT_PUBLIC_BACKEND_URL in .env.local is correct (default: http://localhost:8000).curl http://localhost:8000/api/health/
If you are setting up the project for the first time or experiencing multiple issues, run through this checklist:
node --version should output v20.9.0 (or v20.x.x at minimum).npm --version should be 10.x or later (ships with Node 20).npm install completes without errors.package.json.curl http://localhost:8000/api/health/ returns a response.npm run dev starts without errors on port 3000.http://localhost:3000 renders the application..husky/ directory exists with hook files.| Dev Environment Setup | Initial environment setup |
| Docker Configuration | Docker environment config |
| Environment Configuration | Environment variables per env |
| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Expanded with comprehensive WWAI-specific environment troubleshooting |
| 2026-01-30 | Admin | Initial creation |
Prev: Troubleshooting - Common Errors | Next: Deployment Issues | Up: General