Getting Started
Troubleshooting Common issues and solutions for HRMS development
This guide consolidates common errors from all phases. Use Ctrl+F to search for your error message.
Error Cause Fix P1001: Can't reach databasePostgreSQL not running docker compose up -dP1000: Authentication failedWrong credentials Check DATABASE_URL matches docker-compose.yml Connection refusedPostgreSQL not running docker compose up -dport is already allocatedPort 5432 in use Stop other PostgreSQL: docker stop $(docker ps -q)
Error Cause Fix Cannot find module 'prisma'Prisma not installed Run npm install from root Prisma schema validation errorSchema syntax error Check schema.prisma for typos PrismaClient is not definedPrisma client not generated cd packages/database && npm run db:generate@db.Text not availableWrong Prisma version Check Prisma 5.x installed Unique constraint failedSchema conflict docker compose down -v && docker compose up -dError: ENOENT .env.env file missing cp .env.example .env
# Stop all services docker compose down -v # Start fresh docker compose up -d # Regenerate and push schema cd packages/database npm run db:generate npm run db:push Error Cause Fix redirect_uri_mismatchWrong callback URL in Google Add http://localhost:3000/api/auth/callback/google to Google Console AUTH_SECRET missingNo secret configured Run npx auth secret in apps/web Missing Google credentials.env.local not configured Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
Error Cause Fix tenantId undefined in sessioncreateUser event didn't fire Clear all auth data and re-login session is nullNot logged in Complete OAuth flow first Infinite redirect loopAuth check failing Check AUTH_SECRET and cookies signIn is not a functionWrong import Import from @/auth not next-auth/react signOut is not a functionWrong import Import from @/auth Session still exists after logoutCookie not cleared Check signOut with redirectTo
Error Cause Fix tenantId is null after logincreateUser event didn't fire Clear all user data and re-login Tenant is nulltenantId not in session Re-login after changes
Option A: Clear Browser Data
1. Open DevTools (F12) 2. Application → Cookies → localhost 3. Delete all cookies 4. Refresh page Option B: Clear Database Auth Data
cd packages/database npm run db:studio # In Prisma Studio: # 1. Delete all Session records # 2. Delete all Account records # 3. Delete all User records (if testing fresh) Error Cause Fix npm ERR! code ENOWORKSPACESWorkspaces not configured Ensure package.json has "workspaces" field npm ERR! ENOENTDependencies not installed Run npm install from root ENOENT: no such file or directoryWrong directory Ensure you're in the hrms root directory
Error Cause Fix Module not found: reactDependencies not installed Run npm install from root Port 3000 already in useAnother process using port lsof -ti:3000 | xargs killnext: command not foundNot in apps/web directory cd apps/web firstServer Actions not allowedMissing "use server" Add "use server" inside async function redirect is not a functionWrong import Import from next/navigation
Error Cause Fix Cannot find module '@nestjs/core'Dependencies not installed Run npm install from root Port 3001 already in useAnother process using port lsof -ti:3001 | xargs killnest: command not foundNestJS CLI not available Dependencies should be local, check package.json Cannot GET /healthHealthModule not imported Add HealthModule to AppModule imports Nest can't resolve PrismaServicePrismaModule not global Verify @Global() decorator on PrismaModule database: disconnectedPostgreSQL not running docker compose up -d
Error Cause Fix Cannot find module '@hrms/database'Workspace not linked Run npm install from root Cannot find module '../prisma'PrismaModule not imported Check PrismaModule in imports Cannot find module './prisma'Import path wrong Check import statement
Error Cause Fix API returns 400Missing X-Tenant-ID header Pass tenantId from session in header ForbiddenMissing role header Add X-System-Role header 404 Not FoundWrong tenant ID Get correct ID from Prisma Studio fetch failedNetwork error Check both services running on correct ports API Status: DisconnectedAPI not running Start API with npm run dev
Error Cause Fix CanActivate not foundWrong import Check @nestjs/common import Reflector not foundMissing import Import from @nestjs/core ExecutionContext not foundWrong import Check @nestjs/common import
Error Cause Fix Cannot connect to Docker daemonDocker not running Start Docker Desktop image not foundNetwork issue Check internet, retry docker compose up
# Check if Docker is running docker info # Check container status docker compose ps # Check container logs docker compose logs postgres # Restart containers docker compose restart If all else fails, here's the nuclear option:
# 1. Stop everything docker compose down -v # 2. Remove node_modules rm -rf node_modules rm -rf apps/web/node_modules rm -rf apps/api/node_modules rm -rf packages/database/node_modules # 3. Remove generated files rm -rf apps/web/.next rm -rf apps/api/dist rm -rf packages/database/node_modules/.prisma # 4. Reinstall npm install # 5. Start Docker docker compose up -d # 6. Setup database cd packages/database npm run db:generate npm run db:push # 7. Start services cd ../.. npm run dev If you can't find your error here:
Search the phase documentation - Each phase has step-specific error tablesCheck the constraints - See Constraints Use AI assistance - Follow the AI Coding Agents Guide
Report New Issues
If you encounter an error not listed here, consider adding it to this guide after finding the solution.