clockworklabs/SpacetimeDB · error

Invalid subcommand

Error message

Invalid subcommand: {unknown}

What it means

The CLI's exec (crates/cli/src/lib.rs:77) matches the first positional word against its subcommand table (generate, list, init, build, server, subscribe, start, login, logout, lock, unlock, version, and the arms above the shown region) and falls through to this bail for anything unrecognized. It is the last-resort arm of the dispatcher, so every typo, removed, or not-yet-installed subcommand lands here.

Solutions

1. Run `spacetime --help` and use the exact subcommand name listed for your installed version.
2. Check for typos and case (subcommands are lowercase single words).
3. After upgrading the CLI, re-check the changelog/help for renamed subcommands and update scripts.

Example fix

# before
spacetime publis my-project
# after
spacetime publish my-project

// Shell: validate the subcommand against the CLI's own help before running.
valid=$(spacetime --help 2>&1 | awk '/^Commands:/,/^Options:/' | awk '{print $1}' | grep -vx '^Commands:')
echo "$valid" | grep -qx "$1" || { echo "unknown subcommand: $1 (valid: $(echo $valid | tr '\n' ' '))" >&2; exit 2; }

// Rust embedding the CLI name as a word-check:
const SUBCOMMANDS: &[&str] = &["generate", "list", "init", "build", "server", "subscribe", "start", "login", "logout", "lock", "unlock", "version"];
fn is_subcommand(word: &str) -> bool { SUBCOMMANDS.contains(&word) }

When it happens

Trigger: Running `spacetime <word>` where word is misspelled or not a subcommand (e.g. `spacetime publis`); using a subcommand that was renamed or removed in the installed CLI version; invoking a plugin-style subcommand that this build does not include.

Common situations: Following outdated docs or tutorials against a newer/older CLI; shell autocompletion from another tool; scripts written for a different SpacetimeDB CLI version.

Related errors

• the following required arguments were not provided: <
• the following required arguments were not provided
• Cannot extract accessor name from query
• Cannot extract table name from query
• Cannot semijoin a table to itself

AI-assisted analysis of clockworklabs/SpacetimeDB@eddf9f5014 (2026-08-20). Data as JSON: /api/errors/8134fd970409c1c7. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/lib.rs:80

        "env" => env::exec(config, args).await,
        "delete" => delete::exec(config, args).await,
        "logs" => logs::exec(config, args).await,
        "sql" => sql::exec(config, args).await,
        "mcp" => mcp::exec(config, args).await,
        "rename" => dns::exec(config, args).await,
        "generate" => generate::exec(config, args).await,
        "list" => list::exec(config, args).await,
        "init" => init::exec(config, args).await.map(|_| ()),
        "build" => build::exec(config, args).await.map(drop),
        "server" => server::exec(config, paths, args).await,
        "subscribe" => subscribe::exec(config, args).await,
        "start" => return start::exec(config, paths, args).await,
        "login" => login::exec(config, args).await,
        "logout" => logout::exec(config, args).await,
        "lock" => lock::exec(config, args).await,
        "unlock" => unlock::exec(config, args).await,
        "version" => return subcommands::version::exec(paths, root_dir, args).await,
        unknown => Err(anyhow::anyhow!("Invalid subcommand: {unknown}")),
    }
    .map(|()| ExitCode::SUCCESS)
}

/// An error type indicating that the process should exit silently with the
/// given `ExitCode`.
#[derive(thiserror::Error, Debug)]
#[error("exit with {0:?}")]
pub struct ExitWithCode(pub ExitCode);

impl ExitWithCode {
    /// Basic unsuccessful termination.
    pub const FAILURE: Self = ExitWithCode(ExitCode::FAILURE);
}

View on GitHub (pinned to eddf9f5014)