Troubleshooting¶
Start here¶
This shows what is running, on which port, and at which commit. If a service is missing, read its log:
Logs live in logs/, one file per service.
Common failures¶
"no container runtime found"¶
Docker is not installed, or the daemon is not running. PostgreSQL and Redis run as containers and cannot start without one.
Start Docker Desktop (or podman machine start) and run the installer again.
A port is already in use¶
The installer warns and lets you pick another one. To change ports later:
Defaults are listed in Services and ports.
"uv is too old"¶
Versions below 0.10 reject the PyTorch wheels the AI service needs.
A service will not start¶
Check its log first. The AI service in particular can take several minutes on its first start while it downloads model weights — it is not hung, it is downloading.
Gated model weights fail to download¶
SAM, DINOv3 and similar models need a HuggingFace token. Create a read token
at https://huggingface.co/settings/tokens and add it with
./install.sh --reconfigure.
The label-space assistant does nothing¶
It requires an LLM API key. Without one the feature is simply unavailable.
Configuration changes keep reverting¶
You are probably editing a generated .env file. Those are regenerated by the
installer (keeping a .bak copy). Put durable changes in iquana.conf and
re-run ./install.sh — see Configuration.
Other machines cannot reach the installation¶
The installer's hostname answer must be the hostname or IP that other machines
use, not localhost — it feeds both the frontend's API URL and the backend's
allowed CORS origins. Re-run ./install.sh --reconfigure.
Also check that the host's firewall allows the frontend and backend ports.
People cannot create accounts¶
Self-registration is off by default. Either enable it via
./install.sh --reconfigure, or create the accounts yourself and hand them out.
The first account can always be created either way.
Reporting a bug¶
Please use the issue templates. Steps to reproduce and a screenshot help enormously. Bugs for the frontend, backend, AI service and installer all belong in the same tracker.