/

Help

Troubleshooting

The short list of things that actually go wrong, in the order they usually happen.

The app won't start

  • Run the doctor. bwhale doctor checks your platform's prerequisites and tells you exactly what's missing, with the native command to get it.
  • Launcher Node. The bwhale launcher needs Node >= 20; the app itself ships its own runtime, so that's the only Node requirement.
  • Port already in use. A previous instance may still be holding 24680. Stop it with bwhale stop, then start again.
  • Won't boot after editing credentials. See the YAML entry below — this is the most common cause by far.

"Invalid YAML" or boot errors after adding a key

~/.dsh/.credentials.yaml is indentation-sensitive:

  • Two spaces per nesting level — never tabs.
  • Quote the API key.
  • Lock the file down after editing: chmod 600 ~/.dsh/.credentials.yaml.
  • When in doubt, let the app write the file: Settings → Providers.
correct
version: 1
refs:
  DEEPSEEK_API_KEY: "sk-your-key-here"

Model errors mid-session

  • Auth error — the key in the credentials file is wrong or expired; re-paste it in Settings.
  • Rate limit — that's your provider throttling; wait or switch models in the composer.
  • No key configured — pick a provider in Settings → Providers.

Office file creation fails

Creating xlsx/pptx/docx files needs Python. Baby Whale sets up its own Python environment and installs the libraries it needs (openpyxl, python-pptx, python-docx) on first office use. If that setup failed:

  • Check your network — the first setup downloads packages, behind proxies too.
  • On Linux, make sure python3 is installed; on macOS nothing extra is needed.
  • Retry the task; setup resumes rather than restarts.
  • The session's Trajectory tab shows exactly which step failed.

Previews look rough

Structural previews are the no-dependency default. For pixel-perfect rendering and formula recalculation, install LibreOffice and restart Baby Whale — see Previews & LibreOffice.

Browser didn't open

Start it manually: the UI is at http://127.0.0.1:24680. Over SSH, start with bwhale --no-open and forward the port yourself.

Updating and stopping

bwhale update refreshes to the latest release on next start. Closing the browser tab does not stop the server — use bwhale stop (or bwhale --stop) when you want it gone.

Still stuck?