What causes "Failed to fetch splits." in quickwit-oss/quickwit?

Verify the quickwit server is reachable: `curl /health/readyz`.

Failed to fetch splits.

Error message

Failed to fetch splits.

What it means

describe_split_cli fetches all splits for an index from the metastore through the Quickwit REST client and panics with expect("Failed to fetch splits.") if the HTTP call fails. The panic discards the underlying transport/HTTP error, so a network problem, wrong URL, or server 5xx all surface as this bare message.

Source

Thrown at quickwit/quickwit-cli/src/split.rs:347

        .splits(&args.index_id)
        .mark_for_deletion(args.split_ids)
        .await?;
    println!(
        "{} Splits successfully marked for deletion.",
        "✔".color(GREEN_COLOR)
    );
    Ok(())
}

async fn describe_split_cli(args: DescribeSplitArgs) -> anyhow::Result<()> {
    debug!(args=?args, "describe-split");
    let qw_client = args.client_args.client();
    let list_splits_query_params = ListSplitsQueryParams::default();
    let split = qw_client
        .splits(&args.index_id)
        .list(list_splits_query_params)
        .await
        .expect("Failed to fetch splits.")
        .into_iter()
        .find(|split| split.split_id() == args.split_id.as_str())
        .with_context(|| {
            format!(
                "could not find split metadata in metastore {}",
                args.split_id
            )
        })?;

    println!("{}", make_split_table(&[split], "Split"));

    // TODO: if we have access to the storage, we could fetch that.
    // let split_file = PathBuf::from(format!("{}.split", args.split_id));
    // let (split_footer, _) = read_split_footer(index_storage, &split_file).await?;
    // let stats = BundleDirectory::get_stats_split(split_footer.clone())?;
    // let hotcache_bytes = get_hotcache_from_split(split_footer)?;

    // let mut file_rows = Vec::new();

View on GitHub (pinned to a39730c5cd)

Solutions

Verify the quickwit server is reachable: `curl <endpoint-url>/health/readyz`.
Check --endpoint-url / QW_CONFIG endpoint settings point at the right host and port.
Inspect quickwit server logs for the underlying metastore error and retry after it recovers.

Example fix

// before
.expect("Failed to fetch splits.")
// after
.context("Failed to fetch splits.")?  // preserves the underlying client error via anyhow

Defensive patterns

Strategy: try-catch

Validate before calling

curl -fsS "$QW_ENDPOINT/health/readyz" || echo 'quickwit server not reachable'

Try / catch

let split = client.splits(&index_id).list(params).await
    .context("Failed to fetch splits.")?  // keeps HTTP/network cause instead of panic

Prevention

Confirm the server URL/port before running split commands.
Check `quickwit service is-ready` or the readyz endpoint first.
Look at server-side logs for metastore connectivity (Postgres) problems.

When it happens

Trigger: Calling `quickwit split describe` where the client's GET of split list fails: quickwit server unreachable, wrong --endpoint-url, authentication rejected, or the server returning a non-success status.

Common situations: Quickwit node not running or wrong port in endpoint config; TLS certificate issues; transient network partitions; the metastore (e.g. PostgreSQL) behind the server being down.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/8b752b3649eefa8d. Report an issue: GitHub.