Troubleshooting

Start with the logs: Logs… in the menu, or quail logs -f. The files are in ~/Library/Logs/Quail.

The server won't start

• “Port 8080 is already in use by …” Another program has the port. Quit it, or choose a different port on the Server page.
• Start is greyed out. There's no model the chosen runtime can run. Add one on the Models page — or, if you only have MLX models, choose the Quail server runtime on the Server page.
• It failed. The Server page shows the reason and a Show Logs button.

A model won't load, or is missing

• “Restart to load” on a model's row, or “Models changed — restart to apply” in the menu: the server only knows the models it started with. Restart it.
• “Needs the Quail server runtime”: it's an MLX model and the runtime is llama.cpp.
• Loading fails or the Mac slows to a crawl: the model may be too big. Check its verdict on the Models page, lower its context size, try an 8-bit KV cache, set fewer models loaded at once, or quit memory-hungry apps.

A tool can't connect

• Use the Test button on the Connect page: it makes the same request as the tool and shows the server's error if there is one.
• 401 / “Invalid API key”: the tool has an old key. Copy it again from the Server page. If you just made a new key, restart the server.
• From another device: set Reachable from to Local network, restart, and use the “From other devices” address. Check the Mac's firewall allows Quail.
• The tool says the context is too small, or cuts off: raise the model's context size (coding agents need 32K or more) and restart.

I can't find the window

Click the bird in the menu bar and choose Open Quail. The window opens on your current desktop, even over a full-screen app.

Installing

• macOS says Quail is damaged or can't be checked: official downloads are signed and notarized, so download it again from the releases page. A build of your own made with task build is unsigned and won't open; use task install.
• quail: command not found: install it from General → Command line, and add ~/.local/bin to your PATH.

Reporting a problem

Click About → Copy Details — Quail's versions and your Mac's — and paste them into a new issue, with what you did and what happened. The last lines of quail logs help too.