BOAT
Download

Reference

Troubleshooting

Diagnose installation, service, GPU and model problems.

Start with doctor

boat doctor

It checks the platform, configuration, service manager, accelerator selection and runtime profile, and points at whatever is wrong. boat doctor --fix repairs missing secrets and the autostart unit. When you ask for help, attach the output of boat doctor --report, which is also saved as doctor-report.json.

Read the logs

boat log --follow            # everything, live
boat log backend             # just the API server
boat log model               # model workers
boat log recent --level all  # structured app events

Common problems

boat: command not found

The installer put boat in ~/.local/bin, which is not on your PATH. Add it for the current shell, and add the same line to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

The installer says my platform is unsupported

Releases are built for Ubuntu 22.04/24.04 on x86_64 and macOS on Apple silicon. On other systems, build from source.

The port is already in use

Pick different ports:

boat setup --non-interactive --port 8234 --backend-port 8236

A GPU is present but not used

Check what BOAT detected:

boat doctor --json

If the NVIDIA driver or CUDA probe fails, BOAT reports it rather than quietly using the CPU. Fix the driver, or choose a device explicitly with boat setup --non-interactive --default-device cpu. For a single model, use boat model setup <model> --non-interactive --device <d>.

A model's tools do not show up

  • Confirm it is installed and enabled: boat model list.
  • Make sure the project's annotation type is one the tool supports; other tools are hidden. Check the model's page on this site.
  • The editor refreshes its tool list every 15 seconds and when the tab regains focus.

Out of GPU memory

Each model needs its weight size plus about 0.5 GB. Try a smaller tag, lower --idle-seconds so workers unload sooner, or move a model to another device with boat model setup.

A model install fails verification

BOAT never overwrites local weight files that fail their size or SHA-256 check. The error names the file; delete it or fix the path and install again.

Forgot a password

boat user set-password <user-id>

Still stuck?

Open an issue with your platform, boat version, the output of boat doctor --report and the relevant log lines.

↑↓ navigate↵ open