Troubleshooting GuideCopy Anchor Link

Find quick solutions to common errors encountered during local development and builds.

1. Port 3000 Already in UseCopy Anchor Link

If your terminal reports Error: listen EADDRINUSE: address already in use :::3000:

# Locate the process occupying port 3000 (macOS / Linux)
lsof -i :3000
kill -9 <PID>

# On Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process

2. Docker Container Database Connection RefusedCopy Anchor Link

If Prisma or your service fails to connect to PostgreSQL:

# Verify container status
docker ps -a

# Restart database service
docker compose restart postgres

# Inspect container logs
docker compose logs postgres --tail 50

3. Fumadocs Content Type Generation IssuesCopy Anchor Link

If TypeScript indicates that new MDX pages or properties cannot be found:

npx fumadocs-mdx

This regenerates the .source virtual mapping and types immediately.