Qdrant Not Working? Fix Common Errors

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"

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. 1 Check points exist: GET /collections/{name}/info and look at points_count. If 0, no data was upserted.
2. 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. 3 Filter payload field names are case-sensitive and must match exactly what was stored at upsert time.
4. 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

• 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.