A port the project needs is already taken
Something is already listening on it. Usually a server from an earlier run whose terminal was closed without stopping the process.
The fix
Find what has the port and stop it. Replace 8080 with the port in the message.
# macOS and Linux$lsof -ti:8080 | xargs kill# Windows PowerShell$Get-NetTCPConnection -LocalPort 8080 -State Listen |Select-Object -Expand OwningProcess |ForEach-Object { Stop-Process -Id $_ -Force }
Or move the project instead: change the port in .env. If you change APP_PORT, change APP_URL with it, or links the API generates will point at the old one.
Why it happens
A process keeps its ports until it exits, and closing a terminal window does not always stop what was running in it. The usual culprits are a previous grit start, a dev server from another project, or containers from another project's compose file.
Two ports are special on macOS and are not strays: 5000 belongs to AirPlay Receiver and 7000 to the Control Center. Killing those is not the fix; pick another port, or turn the feature off in System Settings.
A generated project deliberately uses 5434 for Postgres and 6380 for Redis rather than their defaults, precisely so that a native install of either does not collide. If one of those is busy, something else unusual has it.
How to tell it worked
$grit doctor --env
Every port it lists should say free.
Still stuck? The troubleshooting page covers more, and the errors guide lists every message with its cause. Running grit doctor --env checks this machine for all of them at once.
