zeroclaw-labs/zeroclaw · error

Qdrant collection check failed ({status}): {text}

Error message

Qdrant collection check failed ({status}): {text}

What it means

QdrantMemory::ensure_collection probes GET /collections/{name} at construction (new_lazy / ensure_initialized); any probe response that is neither success nor 404 aborts initialization. 404 is the expected "collection missing, create it" signal — every other status (401/403/400/5xx) fails with the status and body, because the follow-up create would fail the same way.

Source

Thrown at crates/zeroclaw-memory/src/qdrant.rs:246

            .request(
                reqwest::Method::GET,
                &format!("/collections/{}", self.collection),
            )
            .send()
            .await;

        match resp {
            Ok(r) if r.status().is_success() => {
                // Collection exists
                return Ok(());
            }
            Ok(r) if r.status().as_u16() == 404 => {
                // Collection doesn't exist, create it
            }
            Ok(r) => {
                let status = r.status();
                let text = r.text().await.unwrap_or_default();
                anyhow::bail!("Qdrant collection check failed ({status}): {text}");
            }
            Err(e) => {
                anyhow::bail!("Qdrant connection failed: {e}");
            }
        }

        // Create collection with vector config
        let create_body = serde_json::json!({
            "vectors": {
                "size": dims,
                "distance": "Cosine"
            }
        });

        let resp = self
            .request(
                reqwest::Method::PUT,
                &format!("/collections/{}", self.collection),

View on GitHub (pinned to 88bb9c8533)

Solutions

  1. Map the status to a fix: 401/403 → correct api_key in [storage.qdrant.<alias>]; 400 → fix the collection name; 5xx → wait/retry or inspect Qdrant logs.
  2. Confirm the URL hits Qdrant's REST port (typically 6333), not the gRPC port, and that no proxy intercepts it.
  3. If auto-create is blocked by permissions, create the collection manually with the vector size/distance config the store expects (size = embedder dimensions, Cosine).

Example fix

# preflight the exact request the store makes
$ curl -H "api-key: $QDRANT_KEY" \
    http://qdrant-host:6333/collections/zeroclaw_memories
# expect 200 (exists) or 404 (will be created); anything else matches this error
Defensive patterns

Strategy: try-catch

Validate before calling

// Preflight the same request ensure_collection makes
let resp = reqwest::Client::new()
    .get(format!("{url}/collections/{collection}"))
    .header("api-key", api_key)
    .send()
    .await?;
match resp.status().as_u16() {
    200 | 404 => Ok(()), // exists, or will be created
    code => anyhow::bail!("qdrant preflight failed with {code}"),
}

Try / catch

let memory = match QdrantMemory::new_lazy("qdrant", &url, &collection, api_key, embedder) {
    m => match m.ensure_initialized().await {
        Ok(()) => m,
        Err(e) if e.to_string().contains("collection check failed") => {
            return Err(e.context("check api_key/collection name in [storage.qdrant.<alias>]"));
        }
        Err(e) => return Err(e),
    },
};

Prevention

When it happens

Trigger: Constructing the qdrant memory store with an invalid API key (401/403), an invalid collection name (400), or while Qdrant errors server-side (5xx) — but where the HTTP connection itself succeeds, distinguishing it from the connection-failed variant.

Common situations: Qdrant Cloud API keys scoped to the wrong project; collection names with characters Qdrant rejects; reverse proxies answering 502/503 before Qdrant sees the request; Qdrant node in maintenance mode.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/8602bc1c1016c12f. Report an issue: GitHub.