clockworklabs/SpacetimeDB · error

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

Error message

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

What it means

SpacetimeConfig's argument validator rejects module-specific CLI flags when the command resolves to more than one module target (target_count > 1). A flag that configures one particular module is meaningless when the operation fans out over several modules, so the error lists the offending flags plus the caller-supplied operation context and resolution hint (typically: name the target or drop the flags).

Source

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

    /// 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 524b4487d9)

Solutions

1. Add the database/module name to the command so it selects a single target
2. Remove the module-specific flags for runs that target all modules
3. Move per-module settings into the spacetime.json entries instead of passing them on the CLI

Example fix

# before (two modules in spacetime.json; --features applies to one)
spacetime publish --features heavy

# after
spacetime publish my-module --features heavy

# Only pass module flags when a single module is targeted
DB_COUNT=$(jq '.modules | length' spacetime.json)
if [ "$DB_COUNT" -gt 1 ] && [ -z "$SPACETIME_DB" ]; then
  echo 'multiple modules: set SPACETIME_DB before using module-specific flags' >&2; exit 2
fi
spacetime publish ${SPACETIME_DB:+"$SPACETIME_DB"} --features "$FEATURES"

let out = Command::new("spacetime").args(args).output()?;
if !out.status.success() {
    let msg = String::from_utf8_lossy(&out.stderr);
    if msg.contains("Cannot use module-specific arguments") {
        // rerun without the flags, or add an explicit database selector
    }
}

When it happens

Trigger: Running a config-aware command (e.g. publish) in a project whose spacetime.json declares multiple modules/databases, while passing one or more module-specific CLI flags, without naming which database/module to operate on.

Common situations: A monorepo spacetime.json grew a second module and an existing CI pipeline still passes the single-module command line; developers copying a working single-module invocation into a multi-module project.

Related errors

• Cannot use generate-entry-specific arguments ({}) when gener
• Failed to parse config file {}: {}
• spacetime.json not found in {}
• Database '{}' is not in the config file. If you want to run
• the following required arguments were not provided: <{}>

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