clockworklabs/SpacetimeDB · error

Invalid subcommand: {unknown}

Error message

Invalid subcommand: {unknown}

What it means

The CLI's hand-rolled dispatcher (crates/cli/src/lib.rs exec) matches the first positional against known subcommands (generate, list, init, build, server, subscribe, start, login, logout, lock, unlock, version, …); the catch-all arm produces this error for anything unrecognized. It is the moral equivalent of clap's 'unrecognized subcommand', including when the word is actually a misspelled or removed command name.

Source

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

        "publish" => publish::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 524b4487d9)

Solutions

1. Run `spacetime help` (or bare `spacetime`) to list the subcommands valid for your installed version
2. Fix the spelling/case of the subcommand
3. If the command used to exist, check `spacetime version` and upgrade the CLI — command names have changed between releases
4. Regenerate shell completions after upgrading so suggestions match

Example fix

# before
spacetime puslish mydb

# after
spacetime publish mydb

const KNOWN = new Set(['generate','list','init','build','server','subscribe','start','login','logout','lock','unlock','version','help']);
const cmd = process.argv[2];
if (!KNOWN.has(cmd)) {
  console.error(`unknown subcommand '${cmd}'; valid: ${[...KNOWN].join(', ')}`);
  process.exit(2);
}

const isSubcommand = (s) =>
  ['generate','list','init','build','server','subscribe','start','login','logout','lock','unlock','version']
    .includes(s);

# In shell wrappers, verify before delegating
spacetime "$cmd" --help >/dev/null 2>&1 || { echo "invalid subcommand: $cmd"; exit 2; }

When it happens

Trigger: Running `spacetime <word>` where <word> is not in the dispatch list — typo, wrong case, or a command that no longer exists in the installed CLI version.

Common situations: Typos like `spacetime buidl`; using subcommands renamed/removed across CLI releases (the spacetime CLI restructured its commands over time); stale shell completions suggesting old names; passing a global flag where the subcommand is expected.

Related errors

• the following required arguments were not provided: <{}>
• the following required arguments were not provided: <datab
• Invalid describe arguments. Usage: spacetime describe [datab
• Unsupported --dotnet-version {version}. Supported values: 8,
• No such saved server configuration: {server} Add a new serve

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