clockworklabs/SpacetimeDB · error

Invalid describe arguments. Usage: spacetime describe [datab

Error message

Invalid describe arguments.
Usage: spacetime describe [database] [entity_type entity_name] --json [--no-config]

What it means

Thrown by `spacetime describe` when the positional arguments left over after database resolution are neither empty nor exactly a `[entity_type entity_name]` pair. `resolve_database_with_optional_parts` consumes the database part first; whatever remains must be `[]` (describe whole database) or exactly 2 strings where the first is `reducer` or `table`. Any other count (e.g. an entity type without a name, or extra trailing tokens) hits the `_` match arm and bails with the usage string.

Source

Thrown at crates/cli/src/subcommands/describe.rs:83

        "spacetime describe [database] [entity_type entity_name] --json [--no-config]",
    )?;
    let entity = match resolved.remaining_args.as_slice() {
        [] => None,
        [entity_type, entity_name] => {
            let entity_type = match entity_type.as_str() {
                "reducer" => EntityType::Reducer,
                "table" => EntityType::Table,
                _ => {
                    anyhow::bail!(
                        "Invalid entity_type '{}'. Expected one of: reducer, table.",
                        entity_type
                    )
                }
            };
            Some((entity_type, entity_name.as_str()))
        }
        _ => {
            anyhow::bail!(
                "Invalid describe arguments.\nUsage: spacetime describe [database] [entity_type entity_name] --json [--no-config]"
            );
        }
    };

    let mut config = config;
    let server_from_cli = args.get_one::<String>("server").map(|s| s.as_ref());
    let server = server_from_cli.or(resolved.server.as_deref());
    let force = args.get_flag("force");
    let anon_identity = args.get_flag("anon_identity");
    let conn = crate::api::Connection {
        host: config.get_host_url(server)?,
        auth_header: get_auth_header(&mut config, anon_identity, server, !force).await?,
        database_identity: database_identity(&config, &resolved.database, server).await?,
        database: resolved.database,
    };
    let api = ClientApi::new(conn);

View on GitHub (pinned to 524b4487d9)

Solutions

1. Count positional args after the database: provide 0 or exactly 2 (`reducer <name>` or `table <name>`)
2. Add the missing entity name: `spacetime describe mydb table my_table --json`
3. Remove trailing extra tokens from the command line
4. Run `spacetime help describe` for the accepted forms

Example fix

# before
spacetime describe mydb table --json
# after
spacetime describe mydb table my_table --json

// Rust (caller-side arg shaping): ensure leftover parts are [] or [type, name]
fn valid_describe_parts(rest: &[String]) -> bool {
    match rest {
        [] => true,
        [t, n] => (t == "reducer" || t == "table") && !n.is_empty(),
        _ => false,
    }
}

When it happens

Trigger: Running `spacetime describe mydb table --json` (entity name missing), `spacetime describe table mytable extra --json` (3 leftover parts), or `spacetime describe mydb reducer r extra --json`. Also occurs when a database is resolved from config and the remaining tokens number anything other than 0 or 2.

Common situations: Forgetting the entity name after `table`/`reducer`, copy-pasting a query-like trailing argument, or assuming `--json` placement among positionals changes parsing. Shell quoting mistakes that split one identifier into two tokens also land here.

Related errors

• the following required arguments were not provided: <{}>
• the following required arguments were not provided: <datab
• Invalid subcommand: {unknown}
• Cannot use module-specific arguments ({}) when {}. {}
• Cannot use generate-entry-specific arguments ({}) when gener

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