clockworklabs/SpacetimeDB · error · anyhow::Error

Cannot use module-specific arguments

Error message

Cannot use module-specific arguments ({}) when {}. {}

What it means

A guard in the CLI's config plumbing: when an operation resolves to more than one target (multiple publish/generate entries in spacetime.json), CLI flags classified as module-specific are rejected because there is no single module to apply them to. The message lists the offending flags plus an operation context and a hint for narrowing to one target.

Solutions

  1. Name the database on the command so exactly one target is selected
  2. Move the module-specific settings into the per-module section of spacetime.json instead of CLI flags
  3. Remove the offending flags for multi-target runs

Example fix

# before
spacetime publish --some-module-only-flag
# with 2+ publish targets in spacetime.json

# after
spacetime publish my-db --some-module-only-flag
# or move the option into that module's spacetime.json entry
Defensive patterns

Strategy: validation

Validate before calling

// before invoking a multi-target operation, assert no module-specific flags are set
if targets.len() > 1 {
    let flags = cfg.module_specific_cli_flags(cmd, matches);
    assert!(flags.is_empty(), "module-specific flags {:?} need a single target", flags);
}

Try / catch

Treat the 'Cannot use module-specific arguments' bail as a usage error: parse the flag list from the message, print the resolution hint, and re-run scoped to one database.

Prevention

When it happens

Trigger: Running a publish/generate operation with 2+ resolved targets while any module-specific CLI flag is present, where the flag's config key is marked module-specific for that command.

Common situations: A spacetime.json with several publish targets plus CLI flags intended for just one of them; migrating a single-module workflow to a multi-module config without moving flags into the config file.

Related errors

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

Appendix: source

Thrown at crates/cli/src/spacetime_config.rs:530

    /// Validate that module-specific CLI flags are not used when operating on multiple targets.
    pub fn validate_no_module_specific_cli_args_for_multiple_targets(
        &self,
        command: &Command,
        matches: &ArgMatches,
        target_count: usize,
        operation_context: &str,
        resolution_hint: &str,
    ) -> anyhow::Result<()> {
        if target_count <= 1 {
            return Ok(());
        }

        let display_args = self.module_specific_cli_flags(command, matches);
        if display_args.is_empty() {
            return Ok(());
        }

        anyhow::bail!(
            "Cannot use module-specific arguments ({}) when {}. {}",
            display_args.join(", "),
            operation_context,
            resolution_hint
        );
    }

    /// Get all generate-entry-specific keys that were provided via CLI.
    pub fn generate_entry_specific_cli_args(&self, matches: &ArgMatches) -> Vec<&str> {
        self.keys
            .iter()
            .filter(|k| k.generate_entry_specific && self.is_from_cli(matches, k.config_name()))
            .map(|k| k.config_name())
            .collect()
    }

    /// Get user-facing CLI flags for generate-entry-specific options provided via CLI.
    pub fn generate_entry_specific_cli_flags(&self, command: &Command, matches: &ArgMatches) -> Vec<String> {

View on GitHub (pinned to eddf9f5014)