What causes "unknown split subcommand `{subcommand}`" in quickwit-oss/quickwit?

Run `quickwit split --help` and use one of describe, list, or mark-for-deletion.

unknown split subcommand `{subcommand}`

Error message

unknown split subcommand `{subcommand}`

What it means

The `quickwit split` CLI only recognizes `describe`, `list`, and `mark-for-deletion` subcommands. Any other token after `split` bails out of `parse_cli_args` with this message. Like other parse-time errors, it occurs before any network call.

Source

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

}

#[derive(Debug, PartialEq)]
pub enum SplitCliCommand {
    List(ListSplitArgs),
    MarkForDeletion(MarkForDeletionArgs),
    Describe(DescribeSplitArgs),
}

impl SplitCliCommand {
    pub fn parse_cli_args(mut matches: ArgMatches) -> anyhow::Result<Self> {
        let (subcommand, submatches) = matches
            .remove_subcommand()
            .context("failed to split subcommand")?;
        match subcommand.as_str() {
            "describe" => Self::parse_describe_args(submatches),
            "list" => Self::parse_list_args(submatches),
            "mark-for-deletion" => Self::parse_mark_for_deletion_args(submatches),
            _ => bail!("unknown split subcommand `{subcommand}`"),
        }
    }

    fn parse_list_args(mut matches: ArgMatches) -> anyhow::Result<Self> {
        let client_args = ClientArgs::parse(&mut matches)?;
        let index_id = matches
            .remove_one::<String>("index")
            .expect("`index` should be a required arg.");
        let offset = matches
            .remove_one::<String>("offset")
            .and_then(|s| s.parse::<usize>().ok());
        let limit = matches
            .remove_one::<String>("limit")
            .and_then(|s| s.parse::<usize>().ok());
        let split_states = matches
            .remove_many::<String>("states")
            .map(|values| {
                values

View on GitHub (pinned to a39730c5cd)

Solutions

Run `quickwit split --help` and use one of describe, list, or mark-for-deletion.
Replace `delete`/`remove` with `mark-for-deletion` (splits are marked then garbage-collected, not deleted inline).
Fix typos/abbreviations (`ls` -> `list`, `inspect` -> `describe`).

Example fix

// before
quickwit split delete --index my-index --split-id 01ABC
// after
quickwit split mark-for-deletion --index my-index --split-id 01ABC

Defensive patterns

Strategy: validation

Validate before calling

const SPLIT_SUBCOMMANDS = ["describe", "list", "mark-for-deletion"];
function isValidSplitSubcommand(cmd: string): boolean {
  return SPLIT_SUBCOMMANDS.includes(cmd);
}

Type guard

function isSplitSubcommand(cmd: string): cmd is "describe" | "list" | "mark-for-deletion" {
  return ["describe", "list", "mark-for-deletion"].includes(cmd);
}

Try / catch

// Exit code 2 (clap usage error) with stderr matching /unknown split subcommand/
const res = await run("quickwit split list --index my-index");
if (res.code === 2 && /unknown split subcommand/.test(res.stderr)) {
  console.error("Use describe, list, or mark-for-deletion.");
}

Prevention

Use `mark-for-deletion` for split removal; there is no `split delete`.
Check `quickwit split --help` before writing new automation.
Do not reuse subcommand vocabulary from `quickwit index` or `quickwit source`.

When it happens

Trigger: Running `quickwit split <invalid> ...`, e.g. `quickwit split delete` (does not exist; use `mark-for-deletion`), `quickwit split ls`, or `quickwit split inspect`.

Common situations: Typing `delete` or `remove` expecting split deletion instead of `mark-for-deletion`; abbreviations like `ls`; scripts written against imagined or older CLI surfaces; mixing up `index`/`source`/`split` subcommand vocabularies.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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