Troubleshooting

Common Issues

"Service Starting..." forever

Check the ready configuration in .hun.yml. If you set ready: "Server started", hun greps the logs for that exact string. If your server actually prints Server is running, hun will never switch from STARTING to RUNNING.

Fix: Update .hun.yml or remove the ready check.

"Address already in use"

This usually happens if:

1. You have a stray process running outside of hun.
2. Two services in the same project try to use the same port.
3. The service ignores its selected Multitask fallback port and does not provide its own available fallback.

Fix:

1. hun stop --all
2. lsof -i :3000 (check for stray processes)
3. kill -9 <PID>

Daemon won't start

Check ~/.hun/logs/daemon.log. Ensure permissions on ~/.hun/daemon.sock are correct (your user should own it).

Reporting Bugs

Please open an issue on GitHub with:

1. Your OS (macOS/Linux)
2. hun --version
3. Relevant logs from ~/.hun/logs/

We appreciate it!