Why is Qdrant not working?

Common reasons Qdrant is not working: (1) Qdrant service outage — check prismix.dev/service/qdrant or status.qdrant.io; (2) collection does not exist or was deleted; (3) vector dimension mismatch — your embeddings must match the dimension set when the collection was created; (4) API key missing or wrong (Qdrant Cloud requires Authorization: Bearer or api-key header); (5) gRPC port 6334 blocked while REST port 6333 is open; (6) Docker container has insufficient memory — Qdrant requires at least 1GB RAM per 1M vectors.

Qdrant connection refused — how to fix?

If Qdrant returns connection refused: (1) for Docker, ensure both ports are exposed: -p 6333:6333 -p 6334:6334; (2) check the container is running with docker ps; (3) verify Qdrant REST API is alive: curl http://localhost:6333/healthz; (4) if using gRPC (port 6334) and getting UNAVAILABLE errors, check your firewall or try switching to REST mode.

Qdrant vector dimension mismatch error

The 'Wrong input: Vector dimension error' means your upserted vectors have a different dimension than the collection was created with. You must recreate the collection with the correct dimension. First delete the existing collection: DELETE /collections/{collection_name}, then recreate it with the correct vector size matching your embedding model (e.g., 1536 for OpenAI text-embedding-3-small, 768 for BGE-base).

Qdrant Cloud 401 Unauthorized error

Qdrant Cloud requires an API key in either the Authorization header (Bearer token) or the api-key header. With the Python client: QdrantClient(url='https://your-cluster.qdrant.io', api_key='your_api_key'). With curl: -H 'api-key: your_api_key'. Without authentication, all Qdrant Cloud requests return 401.

Qdrant search returns empty results

If Qdrant search returns empty results: (1) check the collection has points — GET /collections/{name}/info and verify 'points_count' is > 0; (2) ensure you're querying with the correct vector name if using named vectors; (3) if using filters, verify the payload field names match exactly (case-sensitive); (4) for sparse vectors (SPLADE/BM25), ensure both vectors and sparse_vectors parameters are set correctly.

Qdrant 5 min read

Qdrant Not Working? Fix Common Errors

Troubleshoot Qdrant vector database — connection refused, vector dimension mismatch, 401 auth on Qdrant Cloud, gRPC unavailable, and empty search results.

Qdrant — live status

Updated every 5 minutes · Full incident history →

Full status →

Common errors and fixes

Connection refused / Cannot connect to Qdrant

Qdrant exposes two ports: 6333 (REST/HTTP) and 6334 (gRPC). Both must be exposed in Docker:

docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

Verify Qdrant is responding:

curl http://localhost:6333/healthz
# Expected: "healthz check passed"

Wrong input: Vector dimension error

Error: Wrong input: Vector dimension error: expected dim: 768, got 1536

The vector you're trying to upsert has a different dimension than the collection was created with. You cannot resize an existing collection — delete and recreate it:

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

client = QdrantClient("localhost", port=6333)

# Delete the existing collection
client.delete_collection("my_collection")

# Recreate with the correct dimension
# OpenAI text-embedding-3-small → 1536
# text-embedding-3-large → 3072
# BGE-base-en-v1.5 → 768
# all-MiniLM-L6-v2 → 384
client.create_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
)

Qdrant Cloud — 401 Unauthorized

Qdrant Cloud requires an API key. There are two accepted header formats:

# Python client
from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster.cloud.qdrant.io:6333",
    api_key="your_api_key_here",
)

# curl
curl -H "api-key: your_api_key_here" \
  "https://your-cluster.cloud.qdrant.io:6333/collections"

Get your API key at cloud.qdrant.io → Clusters → Data Access Control → Create API key. Self-hosted Qdrant has no auth by default.

gRPC UNAVAILABLE / gRPC transport error

The Qdrant Python client uses gRPC (port 6334) by default. If port 6334 is blocked or not exposed in Docker, you'll get StatusCode.UNAVAILABLE. Switch to REST mode:

# Force REST mode (port 6333 only)
client = QdrantClient(
    "localhost",
    port=6333,
    prefer_grpc=False,  # default is True
)

Search returns empty results

1 Check points exist: GET /collections/{name}/info and look at points_count. If 0, no data was upserted.
2 Named vectors: if your collection uses named vectors, the search query must specify the vector name: search(collection_name, query_vector=("my_vector_name", [...])).
3 Filter payload field names are case-sensitive and must match exactly what was stored at upsert time.
4 HNSW index not built yet: immediately after a large batch upsert, the index may still be optimizing. Check /collections/{name}/info for optimizer_status.

Out of memory on self-hosted Qdrant

Qdrant keeps all vector data in memory (mmap by default). Rough memory estimate: 1M vectors × 1536 dims × 4 bytes = ~6GB. For large datasets, use quantization:

from qdrant_client.models import ScalarQuantizationConfig, ScalarType

# Scalar quantization: 4x memory reduction, ~5% accuracy loss
client.create_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
    quantization_config=ScalarQuantizationConfig(
        type=ScalarType.INT8,
        quantile=0.99,
        always_ram=True,
    ),
)

Alternatively, set on_disk=True in VectorParams to use mmap instead of RAM — slower but much lower memory usage.

Collection not found error

UnexpectedResponse: Status 404, reason: Not Found: Collection `my_collection` doesn't exist!

List existing collections to check the name: client.get_collections()
If using Docker and restarted without a volume mount, all data is lost on restart. Always use -v $(pwd)/qdrant_storage:/qdrant/storage.
Collection names are case-sensitive: MyCollection ≠ mycollection.

Get an email the next time Qdrant Cloud goes down

Outage alerts for Qdrant Cloud, straight to your inbox. No account needed, unsubscribe in every email.

Watching more than one service? A free account covers 5 services + a daily digest — and Pro is currently free.

FAQ

Qdrant vs Weaviate vs Pinecone — which is more reliable?

All three are production-grade vector databases. Qdrant is fully open-source and can be self-hosted for free. For managed cloud reliability comparison, check prismix.dev/service/qdrant and prismix.dev/service/weaviate for live incident history.

Can I use Qdrant for free?

Yes. Self-hosted Qdrant is free forever (Apache 2 license). Qdrant Cloud offers a free tier with 1GB storage per cluster. Run locally with docker run -p 6333:6333 qdrant/qdrant or install the Python binary.

Slow upsert performance

For bulk inserts, use upsert() with batches of 100–500 points rather than one-by-one. For very large datasets (>1M vectors), use the upload_collection() method which buffers and uploads in parallel. Also temporarily disable indexing during bulk upload: set hnsw_config.m=0 while loading, then re-enable.

Monitor related services

Qdrant status → Weaviate not working → Qdrant status guide → All AI status → All guides →