quickwit-oss/quickwit · error

`--commit-timeout` can only be used with --wait or --force o

Error message

`--commit-timeout` can only be used with --wait or --force options

What it means

Quickwit's `quickwit index ingest` CLI rejects `--commit-timeout` unless the user also explicitly chooses a commit behavior via `--wait` or `--force`. In Auto commit mode the timeout is meaningless because indexing is fire-and-forget, so passing it is treated as a configuration mistake rather than a runtime failure. The check runs during argument parsing, before any client or network work starts.

Source

Thrown at quickwit/quickwit-cli/src/index.rs:397

                .map(|path| path.to_path_buf())
        } else {
            None
        };
        let detailed_response: bool = matches.get_flag("detailed-response");
        let batch_size_limit_opt = matches
            .remove_one::<String>("batch-size-limit")
            .map(|limit| limit.parse::<ByteSize>())
            .transpose()
            .map_err(|error| anyhow!(error))?;
        let commit_type = match (matches.get_flag("wait"), matches.get_flag("force")) {
            (false, false) => CommitType::Auto,
            (false, true) => CommitType::Force,
            (true, false) => CommitType::WaitFor,
            (true, true) => bail!("`--wait` and `--force` are mutually exclusive options"),
        };

        if commit_type == CommitType::Auto && client_args.commit_timeout.is_some() {
            bail!("`--commit-timeout` can only be used with --wait or --force options");
        }

        Ok(Self::Ingest(IngestDocsArgs {
            client_args,
            index_id,
            input_path_opt,
            batch_size_limit_opt,
            commit_type,
            detailed_response,
        }))
    }

    fn parse_search_args(mut matches: ArgMatches) -> anyhow::Result<Self> {
        let index_id = matches
            .remove_one::<String>("index")
            .expect("`index` should be a required arg");
        let query = matches
            .remove_one::<String>("query")

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Add either `--wait` (block until the commit completes) or `--force` (force an immediate commit) to the ingest command.
  2. Remove `--commit-timeout` if you genuinely want Auto commit (default fire-and-forget behavior).
  3. If driven by a script, make the commit flag and timeout consistent (e.g. only append `--commit-timeout` when `--wait`/`--force` is present).

Example fix

// before
quickwit index ingest --index my-index --commit-timeout 30
// after
quickwit index ingest --index my-index --wait --commit-timeout 30
Defensive patterns

Strategy: validation

Validate before calling

const COMMIT_MODES = ["--wait", "--force"];
function validateIngestArgs(args: string[]): string | null {
  const hasTimeout = args.some(a => a.startsWith("--commit-timeout"));
  const hasMode = args.some(a => COMMIT_MODES.includes(a));
  return hasTimeout && !hasMode
    ? "--commit-timeout requires --wait or --force"
    : null;
}

Prevention

When it happens

Trigger: Running `quickwit index ingest --index <idx> --commit-timeout 30` (or reading the timeout from env/config via client args) without passing either `--wait` or `--force`, so `commit_type == CommitType::Auto` while `client_args.commit_timeout.is_some()`.

Common situations: Scripts copied from a `--wait` example but with `--wait` stripped out; users who want faster commits and assume the timeout alone enables waiting; automation that always injects `--commit-timeout` regardless of the commit mode selected elsewhere.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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