`--module-path` cannot be used when `spacetime.json` contain

Error message

`--module-path` cannot be used when `spacetime.json` contains publish targets. Remove `--module-path` or run without publish targets in config.

What it means

`spacetime dev` refuses to mix an explicit `--module-path` CLI flag with a `spacetime.json` that defines publish targets. Publish targets each carry their own `module_path`, so a CLI `--module-path` would be ambiguous — it is only checked when the flag genuinely came from the command line (`ValueSource::CommandLine`), so having the same value in an env var or default does not trigger it.

Source

Thrown at crates/cli/src/subcommands/dev.rs:324

    }

    let spacetime_config = loaded_config.as_ref().map(|lc| &lc.config);
    // A config has publish targets if it has a "database" field or children
    let has_publish_targets_in_config = spacetime_config
        .map(|c| c.additional_fields.contains_key("database") || c.children.is_some())
        .unwrap_or(false);
    let has_generate_targets_in_config = spacetime_config
        .and_then(|c| c.generate.as_ref())
        .map(|g| !g.is_empty())
        .unwrap_or(false);

    let module_path_from_cli_flag = args.value_source("module-path") == Some(ValueSource::CommandLine);
    let project_path_from_cli_flag = args.value_source("project-path") == Some(ValueSource::CommandLine);
    let module_bindings_path_from_cli_flag =
        args.value_source("module-bindings-path") == Some(ValueSource::CommandLine);

    if has_publish_targets_in_config && module_path_from_cli_flag {
        anyhow::bail!(
            "`--module-path` cannot be used when `spacetime.json` contains publish targets. \
             Remove `--module-path` or run without publish targets in config."
        );
    }

    if has_generate_targets_in_config
        && (module_path_from_cli_flag || project_path_from_cli_flag || module_bindings_path_from_cli_flag)
    {
        anyhow::bail!(
            "`--module-path`, `--project-path`, and `--module-bindings-path` cannot be used when \
             `spacetime.json` contains generate targets. Remove these flags or remove generate targets from config."
        );
    }

    // Fetch the database name if it was passed through a CLI arg
    let database_name_from_cli: Option<String> = args
        .get_one::<String>("database")
        .or_else(|| args.get_one::<String>("database-flag"))

View on GitHub (pinned to 524b4487d9)

Solutions

Drop `--module-path` and set `module_path` on each publish target in `spacetime.json`
Or temporarily remove/disable the publish targets from `spacetime.json` if the flag must stay
Update wrapper scripts/aliases to not pass `--module-path` in publish-target projects

Example fix

# before
spacetime dev --module-path ./spacetimedb
# (spacetime.json has "publish": [{ "database": "db", "module_path": "./spacetimedb" }])
# after
spacetime dev

Defensive patterns

Strategy: validation

Validate before calling

# Only pass --module-path when there are no publish targets
if jq -e '.publish | length > 0' spacetime.json >/dev/null 2>&1; then
  spacetime dev
else
  spacetime dev --module-path ./spacetimedb
fi

Prevention

Pick one source of truth for module paths: config OR flags, never both
Audit wrapper scripts when adding publish targets to spacetime.json

When it happens

Trigger: Running `spacetime dev --module-path ./src` when `spacetime.json` has a non-empty `publish` array (even a single target).

Common situations: Adding publish targets to config on a project that previously used `--module-path` habitually; copy-pasting a dev command from docs into a multi-target repo; wrapper scripts that always pass `--module-path`.

Related errors

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