quickwit-oss/quickwit · error

unknown source subcommand `{subcommand}`

Error message

unknown source subcommand `{subcommand}`

What it means

The `quickwit source` CLI dispatches to a fixed set of subcommands (create, delete, describe, list, reset-checkpoint). Any unrecognized first argument after `source` fails argument parsing with this message. It is a usage error surfaced by clap's `remove_subcommand` fallback, so nothing is sent to the server.

Source

Thrown at quickwit/quickwit-cli/src/source.rs:250

        let (subcommand, submatches) = matches
            .remove_subcommand()
            .context("failed to parse source subcommand")?;
        match subcommand.as_str() {
            "create" => Self::parse_create_args(submatches).map(Self::CreateSource),
            "update" => Self::parse_update_args(submatches).map(Self::UpdateSource),
            "enable" => {
                Self::parse_toggle_source_args(&subcommand, submatches).map(Self::ToggleSource)
            }
            "disable" => {
                Self::parse_toggle_source_args(&subcommand, submatches).map(Self::ToggleSource)
            }
            "delete" => Self::parse_delete_args(submatches).map(Self::DeleteSource),
            "describe" => Self::parse_describe_args(submatches).map(Self::DescribeSource),
            "list" => Self::parse_list_args(submatches).map(Self::ListSources),
            "reset-checkpoint" => {
                Self::parse_reset_checkpoint_args(submatches).map(Self::ResetCheckpoint)
            }
            _ => bail!("unknown source subcommand `{subcommand}`"),
        }
    }

    fn parse_create_args(mut matches: ArgMatches) -> anyhow::Result<CreateSourceArgs> {
        let client_args = ClientArgs::parse(&mut matches)?;
        let index_id = matches
            .remove_one::<String>("index")
            .expect("`index` should be a required arg.");
        let source_config_uri = matches
            .remove_one::<String>("source-config")
            .map(|uri_str| Uri::from_str(&uri_str))
            .expect("`source-config` should be a required arg.")?;
        Ok(CreateSourceArgs {
            client_args,
            index_id,
            source_config_uri,
        })
    }

View on GitHub (pinned to a39730c5cd)

Solutions

1. Run `quickwit source --help` to list the valid subcommands and use one of them exactly.
2. Fix the spelling of the subcommand (e.g. `ls` -> `list`, `creat` -> `create`).
3. Check your Quickwit version; if following older docs, use the documented subcommand set (create, delete, describe, list, reset-checkpoint).

Example fix

// before
quickwit source ls --index my-index
// after
quickwit source list --index my-index

const SOURCE_SUBCOMMANDS = ["create", "delete", "describe", "list", "reset-checkpoint"];
function isValidSourceSubcommand(cmd: string): boolean {
  return SOURCE_SUBCOMMANDS.includes(cmd);
}

function isSourceSubcommand(cmd: string): cmd is "create" | "delete" | "describe" | "list" | "reset-checkpoint" {
  return ["create", "delete", "describe", "list", "reset-checkpoint"].includes(cmd);
}

// Exit code 2 (clap usage error) with stderr matching /unknown source subcommand/
const res = await run("quickwit source list --index my-index");
if (res.code === 2 && /unknown source subcommand/.test(res.stderr)) {
  console.error("Fix the subcommand; run `quickwit source --help`.");
}

When it happens

Trigger: Running `quickwit source <anything-not-in {create,delete,describe,list,reset-checkpoint}> ...`, e.g. typos like `quickwit source ls`, `quickwit source creat`, or a subcommand that exists for another noun (e.g. `quickwit source update`).

Common situations: Typo or abbreviated subcommand; muscle memory from other CLIs (`ls`/`rm` instead of `list`/`delete`); following outdated docs where a subcommand was renamed; shell scripts referencing an older Quickwit version's syntax.

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

• unknown split subcommand `{subcommand}`
• `--commit-timeout` can only be used with --wait or --force o
• unknown output format `{output_format_str}`. supported forma
• failed to parse --{}-date option parameter `{}`. supported f
• file extension `.{ext}` is not supported. supported file for

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