Qdrant Connection Refused (localhost:6333 / Docker)

How to fix it

Try these in order — the most common fix is first.

1. 1. Check Qdrant is up

   Copy steps
   1. Run docker ps and look for the qdrant container
   2. Run curl http://localhost:6333/healthz
   3. Read docker logs <container> for startup panics
   Did this fix it? Yes No

2. 2. Publish both ports

   Copy steps
   1. Start with docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
   2. In Compose, add both ports mappings
   Did this fix it? Yes No

3. 3. Fix the hostname

   Copy steps
   1. Inside Docker Compose use http://qdrant:6333, not localhost
   2. On Mac/Windows try 127.0.0.1 instead of localhost
   Did this fix it? Yes No

4. 4. Force REST or raise the timeout

   Copy steps
   1. QdrantClient(url=..., prefer_grpc=False)
   2. QdrantClient(..., timeout=60) for slow operations
   Did this fix it? Yes No

Symptoms

Python client or curl fails with "connection refused" or a timeout when connecting to Qdrant on localhost:6333.

Why it happens

• Container not running or crashed on startup
• Port 6333 (REST) or 6334 (gRPC) not published with -p
• App running in another container using localhost instead of the Qdrant service name
• Client using gRPC (port 6334) while only 6333 is open
• Large existing dataset delaying startup by tens of seconds

This guide also covers

• qdrant connection refused
• qdrant docker connection refused localhost 6333
• qdrant timeout python client

The same problem in other apps

All not loading, error messages & connection guides →

• Pinecone 429 Too Many Requests Error (Pinecone)
• Weaviate Error: Vector Lengths Don't Match (Weaviate)
• Milvus "collection not loaded" Error (Milvus)
• Chroma "Your system has an unsupported version of sqlite3" Error (Chroma)

Other Qdrant errors

• Qdrant "Wrong input: Vector dimension error: expected dim, got"
• Qdrant "Not found: Collection doesn't exist" Error
• Qdrant Out of Memory (OOMKilled / High RAM Usage)
• Why Is Qdrant Search Slow? HNSW, Quantization and Segment Settings
• Qdrant Free Cluster Suspended or Deleted After Inactivity
• Qdrant Snapshot Restore Failed
• How to Cancel Qdrant Cloud and Delete a Cluster