clockworklabs/SpacetimeDB · error · anyhow::Error

Invalid subcommand: {unknown}

Error message

Invalid subcommand: {unknown}

What it means

`exec` in the server subcommand module dispatches on the subcommand string (`list`, `set-default`, `add`, `remove`, `fingerprint`, `ping`, `edit`, `clear`). An unrecognized token falls into the `unknown` catch-all arm and is returned verbatim in this error. Clap normally rejects unknown subcommands earlier, so this arm mainly fires when the dispatch is reached programmatically or argument parsing was bypassed.

Source

Thrown at crates/cli/src/subcommands/server.rs:137

    exec_subcommand(config, paths, cmd, subcommand_args).await
}

async fn exec_subcommand(
    config: Config,
    paths: &SpacetimePaths,
    cmd: &str,
    args: &ArgMatches,
) -> Result<(), anyhow::Error> {
    match cmd {
        "list" => exec_list(config, args).await,
        "set-default" => exec_set_default(config, args).await,
        "add" => exec_add(config, args).await,
        "remove" => exec_remove(config, args).await,
        "fingerprint" => exec_fingerprint(config, args).await,
        "ping" => exec_ping(config, args).await,
        "edit" => exec_edit(config, args).await,
        "clear" => exec_clear(config, paths, args).await,
        unknown => Err(anyhow::anyhow!("Invalid subcommand: {unknown}")),
    }
}

#[derive(Tabled)]
#[tabled(rename_all = "UPPERCASE")]
struct LsRow {
    default: String,
    hostname: String,
    protocol: String,
    nickname: String,
}

pub async fn exec_list(config: Config, _args: &ArgMatches) -> Result<(), anyhow::Error> {
    let mut rows: Vec<LsRow> = Vec::new();
    for server_config in config.server_configs() {
        let default = if let Some(default_name) = config.default_server_name() {
            server_config.nick_or_host_or_url_is(default_name)
        } else {

View on GitHub (pinned to 524b4487d9)

Solutions

1. Run `spacetime server --help` and use one of the listed subcommands exactly
2. Check for typos in the subcommand token
3. If you expected the subcommand to exist, update the CLI (`spacetime update`) — the parser and dispatcher may be from different versions

Example fix

# before
spacetime server ls
# after
spacetime server list

# Validate the subcommand token before invoking
[[ " list set-default add remove fingerprint ping edit clear " == *" $1 "* ]] || { echo "unknown: $1"; exit 2; }
spacetime server "$@"

When it happens

Trigger: Invoking the internal dispatch with an arbitrary string, a typo that slips past clap's validation layer, or a new subcommand name that exists in the CLI spec but not in this match arm (version drift between the parser definition and this dispatcher).

Common situations: Running a newer/older CLI binary where the subcommand table is out of sync; scripts calling `spacetime server <typo>`; shell aliases mangling the subcommand token.

Related errors

• Server already configured for host: {host}
• Nickname {} conflicts with saved configuration for server {}
• Host {} conflicts with saved configuration for server {}: {}
• Invalid url: {url}
• Unsupported --dotnet-version {version}. Supported values: 8,

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/27def51d0d3a9ae4. Report an issue: GitHub.