Troubleshooting¶
Common problems with the Qdrant vector database, what causes them and how to fix them.
401 or 403 from the API¶
Cause: the call was sent without the api-key header, or with a key that
does not match /etc/qdrant/credentials/api.key, often after a rotation.
Fix: use sudo /opt/sushi/bin/qdrant-api, or send the current key in the
api-key header from your client.
qdrant-api: refusing an argument that can place a secret on the command line¶
Cause: you passed a header, a user or an API key to the helper. It adds the key itself and refuses these arguments.
Fix: pass only the method, the path and an optional JSON body, for example
sudo /opt/sushi/bin/qdrant-api GET /collections.
qdrant-api must run as root¶
Cause: the helper reads the root-only key file.
Fix: run it with sudo.
Connection refused from another host¶
Cause: Qdrant listens on 127.0.0.1 only.
Fix: use Session Manager port forwarding, or put a TLS reverse proxy on the instance, see Reach Qdrant from other machines.
Qdrant does not start after a configuration change¶
Cause: the first-boot check found a setting it does not allow, such as a
host other than 127.0.0.1, TLS, CORS, the web UI or cluster mode turned
on. Qdrant depends on that check, so it does not start.
Fix: read the reason, restore the setting, then start again, see What the first-boot check enforces:
sudo journalctl -u sushi-qdrant-firstboot --no-pager
sudo systemctl restart sushi-qdrant-firstboot
sudo systemctl start qdrant
Legacy Qdrant identity needs an explicit trusted migration¶
Cause: a credentials directory exists under /var/lib/qdrant, for
example after restoring files into the wrong place. First boot will not move
it.
Fix: move the key into /etc/qdrant/credentials/ yourself, remove the
directory under /var/lib/qdrant, and restart the first-boot service.
Requests fail with a size error¶
Cause: the request body is larger than max_request_size_mb (32 MB by
default).
Fix: upsert points in smaller batches, or raise the limit in
/etc/qdrant/config.yaml and restart.
If it still fails, contact info@softwaresushi.com.
Last updated October 13, 2026 · Suggest an improvement