From e34f3bf4a115033a7ff9f8fb61f1ec5d98b950d2 Mon Sep 17 00:00:00 2001
From: The Chronicler <claude@firefrostgaming.com>
Date: Tue, 24 Feb 2026 09:28:38 +0000
Subject: [PATCH] docs: Add Dify-Qdrant connection refused troubleshooting
 guide

- Documents QDRANT_URL vs QDRANT_HOST/PORT issue
- Provides step-by-step diagnosis and resolution
- Includes common mistakes and verification checklist
- Chronicles 3+ hour debugging session resolution

Fixes catastrophic failure between Chronicler #25 and #26 sessions.
---
 .../dify-qdrant-connection-refused.md         | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 docs/troubleshooting/dify-qdrant-connection-refused.md

diff --git a/docs/troubleshooting/dify-qdrant-connection-refused.md b/docs/troubleshooting/dify-qdrant-connection-refused.md
new file mode 100644
index 0000000..3897539
--- /dev/null
+++ b/docs/troubleshooting/dify-qdrant-connection-refused.md
@@ -0,0 +1,124 @@
+# 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:**
+```bash
+# 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:**
+```yaml
+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:**
+```bash
+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):**
+```bash
+docker-compose down
+docker-compose up -d
+```
+
+4. **Verify:**
+```bash
+# 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:
+
+```python
+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:**
+```yaml
+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:**
+```bash
+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.**