What causes "typesense collection check failed ({})" in nikivdev/code?

Check the status code: 401/403 -> fix api_key; 5xx -> inspect Typesense server logs

typesense collection check failed ({})

Error message

typesense collection check failed ({})

What it means

typesense_ensure_collection first GETs the collection endpoint to see if it exists. Any non-success status other than 404 (which means 'create it') is treated as an unexpected failure and bails with 'typesense collection check failed (<status>)'.

Source

Thrown at src/install.rs:724

fn typesense_ensure_collection(config: &TypesenseConfig) -> Result<()> {
    let client = Client::builder()
        .timeout(std::time::Duration::from_secs(5))
        .build()?;
    let base = config.url.trim_end_matches('/');
    let get_url = format!("{}/collections/{}", base, config.collection);
    let mut request = client.get(&get_url);
    if !config.api_key.is_empty() {
        request = request.header("X-TYPESENSE-API-KEY", &config.api_key);
    }
    let resp = request
        .send()
        .context("failed to check typesense collection")?;
    if resp.status().is_success() {
        return Ok(());
    }
    if resp.status().as_u16() != 404 {
        bail!("typesense collection check failed ({})", resp.status());
    }

    let create_url = format!("{}/collections", base);
    let schema = serde_json::json!({
        "name": config.collection,
        "fields": [
            { "name": "id", "type": "string" },
            { "name": "pkg_path", "type": "string" },
            { "name": "description", "type": "string", "optional": true },
            { "name": "version", "type": "string", "optional": true }
        ],
        "default_sorting_field": "pkg_path"
    });
    let mut create_req = client.post(&create_url).json(&schema);
    if !config.api_key.is_empty() {
        create_req = create_req.header("X-TYPESENSE-API-KEY", &config.api_key);
    }
    let resp = create_req

View on GitHub (pinned to a747e741ae)

Solutions

Check the status code: 401/403 -> fix api_key; 5xx -> inspect Typesense server logs
Verify the base URL/collection name in TypesenseConfig
Curl GET {base}/collections/{collection} with the key to reproduce
Upgrade/downgrade Typesense if it returns non-404 for missing collections

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight collection check with the same key
let resp = reqwest::Client::new()
    .get(format!("{}/collections/{}", base, collection))
    .header("X-TYPESENSE-API-KEY", &api_key)
    .send().await?;
println!("collection check status: {}", resp.status());

Try / catch

match run_index() {
    Err(e) if e.to_string().contains("typesense collection check failed") => {
        eprintln!("Cannot verify collection: {} — check key/server", e);
    }
    other => other?,
}

Prevention

Use an API key with read access to collections
Confirm base URL/port before running run_index
Verify your Typesense version returns 404 (not another status) for missing collections

When it happens

Trigger: The collection-existence GET returns 401/403 (bad API key), 5xx (server error), or any non-404 error status during run_index.

Common situations: Wrong API key lacking read access; Typesense unreachable/misconfigured and a proxy returns 502; Typesense version returning an unexpected status for missing collections (e.g. 400 instead of 404).

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/ac892c5802c5e9a9. Report an issue: GitHub.