clockworklabs/SpacetimeDB · error · anyhow::Error

Invalid describe arguments.\nUsage: spacetime describe [data

Error message

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

What it means

The positional arguments after the database name in `spacetime describe` must be either empty or exactly an (entity_type, entity_name) pair. One argument (entity type without a name) or three or more arguments falls into the wildcard arm and bails with the usage line.

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 6dee26c6ef)

Solutions

1. Pass either no entity args or exactly `entity_type entity_name`
2. Quote multi-word entity names
3. Put flags before the positional arguments or after `--`

Example fix

# before
spacetime describe my-db table

# after
spacetime describe my-db table person

// arity check before invoking describe
assert!(
    remaining_args.is_empty() || remaining_args.len() == 2,
    "expected no args or exactly [entity_type entity_name]"
);

fn valid_describe_args(args: &[String]) -> bool {
    matches!(args.len(), 0 | 2)
}

When it happens

Trigger: `spacetime describe my-db table` (entity type given but no name), or any extra positional argument after the pair.

Common situations: Forgetting the entity name; shell quoting that splits one name into two args; flags appended after positionals without a separator.

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

• Invalid entity_type '{}'. Expected one of: reducer, table.
• Too many positional arguments for interactive mode. Usage: s
• Missing type name for ${typeBuilder.constructor.name ?? 'Typ
• Cannot use module-specific arguments ({}) when {}. {}
• Invalid subcommand: {unknown}

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/289a3c3f68dcbf09. Report an issue: GitHub.