Troubleshooting

Docker not responding

The sidebar shows red and a Start Docker button. The app uses docker desktop start --detach first (Docker 4.30+ has this CLI command, and it un-pauses a paused engine), then falls back to open -a Docker. Allow 30 to 60 seconds for the daemon to come up.

If docker info works in your terminal but the app says Docker is down, the engine might be paused (Docker Desktop, then Resources, then Pause). Resume it.

500s on a fresh project

Almost always a missing sessions table. Sail Manager runs php artisan migrate --force automatically after start, so this should be rare. If it happens, check the auto-command logs for migration errors and run Run command, then php artisan migrate manually.

Port conflicts

Something else is bound to one of the host ports. Stop the conflicting service, or restart Docker (sometimes a previous Sail process holds a port). The error message will tell you which port is in trouble.

Local URLs not loading

Open Settings and check the Local URLs status panel. It runs five checks:

• Resolver file present at /etc/resolver/<tld>
• dnsmasq container running
• Traefik proxy container running
• Proxy port (80 or your configured port) bound
• DNS actually resolving queries

The panel tells you which one failed. Click Resync to rebuild everything.

Untracked projects

The app spotted folders inside your projects directory that look like Sail projects but aren't registered (probably because you cloned them outside the app, or imported a backup). Click Import all in the toast and they'll show up in the list.

Shell echoes weird characters

An older bug caused the shell tab to echo ggggg… on connection due to missing terminal type forwarding. Update to the latest release — the fix sets TERM=xterm-256color properly.