Help
Qdrant, Weaviate and Meilisearch errors and how to fix them
Tested with:Databasezy API v1 · zb CLI 0.1
Qdrant and Meilisearch are available on every plan, including Free. Weaviate is available on paid plans only. All
three are reached over HTTPS on port 443 (8443 in single-IP regions) and authenticate with one API key per instance.
Qdrant and Weaviate also serve gRPC on a second host name ending in -grpc. A rotation restarts the instance, and the
old key stops working at that restart. There is no overlap window.
Errors on all three engines
Section titled “Errors on all three engines”The connection closes during the TLS handshake
Section titled “The connection closes during the TLS handshake”Cause: the gateway closes the connection without an HTTP response in these cases:
- the client used
http:// - the client connected by IP address
- your address is not on the allow-list
- your address is temporarily blocked after repeated failed requests
Fix: use the https:// host from the Connect tab, and add your egress CIDR under Network → IP allow-list. See
IP allow-lists.
503 paused or waking up, 429 too many connections
Section titled “503 paused or waking up, 429 too many connections”Cause: the gateway answers these itself, with JSON such as {"error": "paused", ...}, wake_timeout,
too_many_connections or rate_limited. Free instances sleep after 15 minutes without connections. The first request
is held for up to 30 seconds while the instance wakes (wake_timeout if it is not ready in time). paused means
someone paused the instance on purpose, or support did as the message says; requests never wake it. Connections are
capped by the size, and at 50 new connections per second.
Fix: retry after wake_timeout. For paused, run zb instances resume <instance_id> (support pauses need
support). For a 429, wait for the Retry-After header. See
Paused and waking instances.
Qdrant
Section titled “Qdrant”Timeouts from the Python client
Section titled “Timeouts from the Python client”Cause: without an explicit port, the Python client assumes Qdrant’s default port 6333, which is not exposed.
Fix: keep :443 in the URL, or pass port=443 (8443 in single-IP regions).
401 Unauthorized
Section titled “401 Unauthorized”Cause: the key is missing or wrong, or it was rotated.
Fix: send the key in the api-key header (or Authorization: Bearer) on REST, and as api-key metadata on gRPC.
Reveal the current key with zb instances credentials reveal <instance_id>.
REST works but gRPC does not
Section titled “REST works but gRPC does not”Cause: the gRPC client is pointed at the REST host.
Fix: use the -grpc host name (for example with prefer_grpc=True in Python), also on port 443.
Out of memory, or the instance restarts during upserts
Section titled “Out of memory, or the instance restarts during upserts”Cause: by default, vectors and the HNSW index are held in memory.
Fix: store vectors on disk (on_disk: true), turn on quantization, or resize. REST bodies are
limited to 32 MB by default, so batch large upserts.
Read-only keys for a front end
Section titled “Read-only keys for a front end”These are not available. The instance has one key with full access. Keep it on your servers.
Weaviate
Section titled “Weaviate”401 Unauthorized
Section titled “401 Unauthorized”Cause: anonymous access is off. The request has no key, the wrong key, or a rotated key.
Fix: pass the key as the client’s API-key credential. Plain HTTP sends Authorization: Bearer <key>.
The v4 Python or v3 TypeScript client fails while REST works
Section titled “The v4 Python or v3 TypeScript client fails while REST works”Cause: these clients need both endpoints. They use REST for schema calls and gRPC for queries and imports.
Fix: set grpc_host to the -grpc host name on port 443 with TLS, and allow both host names through your egress
firewall.
nearText, hybrid search or a generative query fails
Section titled “nearText, hybrid search or a generative query fails”Cause: no vectorizer or generative modules are enabled, so Weaviate cannot create embeddings.
Fix: compute vectors yourself. Send them with your objects, and use nearVector or pass a vector to hybrid search.
Writes refused for memory, or the instance restarts
Section titled “Writes refused for memory, or the instance restarts”Cause: the vector indexes outgrew the size’s memory.
Fix: use quantization, use the flat index for small tenants, or resize.
Meilisearch
Section titled “Meilisearch”401 with missing_authorization_header, or 403 with invalid_api_key
Section titled “401 with missing_authorization_header, or 403 with invalid_api_key”Cause: the key is missing, or it is not valid for this action or index. Every key’s value comes from the master key, so a rotation changes every key value: the default keys and the ones you created.
Fix: reveal the new master key. List the new key values with GET /keys and redeploy them. The same applies after
a restore into a new instance.
Writes “succeed” but the data is not there yet
Section titled “Writes “succeed” but the data is not there yet”Cause: writes are queued as tasks and processed asynchronously.
Fix: poll GET /tasks/<uid>, or use your SDK’s wait helper, and check the task for an error.
The instance restarts while indexing, and the same task runs again
Section titled “The instance restarts while indexing, and the same task runs again”Cause: a large import ran out of memory. Meilisearch retries the task at every restart. The Free size suits small indexes of a few thousand documents.
Fix: while the server is up, run POST /tasks/cancel?statuses=enqueued,processing with the master key. Then resize
and send the documents in smaller batches. Payloads are capped at 100 MB.
Which key can go in the browser?
Section titled “Which key can go in the browser?”Never put the master key or an admin key in front-end code. Create a search-only key limited to the indexes the page
needs with POST /keys.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket) and include:
- the instance id, engine and region
- REST or gRPC
- the HTTP status and the error body
- your client library and its version
- the time of the failure in UTC
Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.