firefrost-operations-manual/docs/troubleshooting/dify-qdrant-connection-refused.md

Dify + Qdrant "Connection Refused" Error

Problem: Dify worker shows qdrant_client.http.exceptions.ResponseHandlingException: [Errno 111] Connection refused

Symptoms:

• Documents stuck in "Queuing" status
• Re-indexing fails
• Qdrant container is running and healthy
• curl http://qdrant:6333/collections works from worker container
• But Python Qdrant client cannot connect

Root Cause: Dify's Qdrant client expects QDRANT_URL environment variable in full URL format (http://host:port), NOT separate QDRANT_HOST and QDRANT_PORT variables.

Diagnosis:

# Check what Dify sees
docker exec firefrost-codex_dify-worker_1 python3 -c "
from configs import dify_config
print('QDRANT_URL:', dify_config.QDRANT_URL)
"

# If output is "None", the variable is not set correctly

Solution:

1. Check docker-compose.yml environment section:

dify-api:
  environment: &dify-env
    VECTOR_STORE: qdrant
    QDRANT_URL: http://qdrant:6333  # ✅ CORRECT - full URL
    # NOT THIS:
    # QDRANT_HOST: qdrant            # ❌ WRONG
    # QDRANT_PORT: 6333              # ❌ WRONG

2. Fix docker-compose.yml:

cd /opt/firefrost-codex

# Remove old format if present
sed -i '/QDRANT_HOST:/d' docker-compose.yml
sed -i '/QDRANT_PORT:/d' docker-compose.yml

# Add correct format (if not already present)
# Manually edit to add under VECTOR_STORE line:
# QDRANT_URL: http://qdrant:6333

3. Recreate containers (required for env var changes):

docker-compose down
docker-compose up -d

4. Verify:

# Should show: QDRANT_URL=http://qdrant:6333
docker exec firefrost-codex_dify-worker_1 env | grep QDRANT_URL

5. Test indexing:

• Go to Dify web interface
• Navigate to Knowledge Base
• Click "Re-index"
• Documents should start turning green (Indexed status)

Why This Happens:

Dify's QdrantConfig class (in /app/api/configs/middleware/vdb/qdrant_config.py) defines:

QDRANT_URL: str | None = Field(
    description="URL of the Qdrant server (e.g., 'http://localhost:6333')",
    default=None,
)

The older QDRANT_HOST / QDRANT_PORT format is NOT recognized by modern Dify versions.

Common Mistakes:

1. Hardcoded IP instead of service name:

QDRANT_URL: http://172.19.0.4:6333  # ❌ IP can change on restart
QDRANT_URL: http://qdrant:6333      # ✅ Service name is stable

2. Using .env file but docker-compose.yml overrides:

• docker-compose.yml environment values OVERRIDE .env file
• Always check docker-compose.yml first

3. Forgetting to recreate containers:

docker-compose restart  # ❌ Does NOT reload environment variables
docker-compose down && docker-compose up -d  # ✅ Recreates with new env

Verification Checklist:

• Qdrant container is running: docker ps | grep qdrant
• Network connectivity works: docker exec firefrost-codex_dify-worker_1 curl -s http://qdrant:6333/collections
• Environment variable is set: docker exec firefrost-codex_dify-worker_1 env | grep QDRANT_URL
• Variable format is correct: Should be http://qdrant:6333, not empty or IP
• Containers were recreated after config change
• No errors in worker logs: docker-compose logs dify-worker | grep -i error

Related Issues:

• See: docs/tasks/firefrost-codex/ for Phase 5 deployment details
• See: Chronicler #25 (The Foundation) memorial for initial deployment
• See: Chronicler #26 session for troubleshooting this exact issue

Created: February 24, 2026
Created By: Chronicler #26
Issue Resolved: February 24, 2026 (3+ hour debugging session)

---

💙🔥❄️

The best debugging sessions are the ones that become documentation for the next person.