clockworklabs/SpacetimeDB · error

--env-only cannot reset a database

Error message

--env-only cannot reset a database

What it means

`spacetime publish --env-only` publishes only updated environment variables to an existing database and must never clear/reset it. The CLI enforces this by rejecting any combination where `--env-only` is combined with a reset mode (`--clear-database` / `ClearMode` other than `Never`). The two options are semantically contradictory, so publish fails fast.

Solutions

1. Remove `--clear-database` (or set it to `never`) from the command when using `--env-only`.
2. Split the operation: run a normal publish with the clear flag when a reset is needed, and a separate `--env-only` publish when only environment variables change.
3. Fix wrapper scripts/CI templates so the clear flag is only passed on full publishes.
4. Use `--env-only` as-is for pure env updates — it already requires only an existing database name/identity.

Example fix

# before
spacetime publish --env-only --clear-database yes my-db
# after (env-only update, no reset)
spacetime publish --env-only my-db

#!/bin/sh
# guard in publish wrapper
if echo "$ARGS" | grep -q -- '--env-only' && echo "$ARGS" | grep -q -- '--clear-database'; then
  echo "--env-only cannot be combined with --clear-database" >&2; exit 1
fi

When it happens

Trigger: Running `spacetime publish --env-only ...` together with `--clear-database yes|no` (any `ClearMode != Never`), or with defaults elsewhere wiring a non-Never clear mode while `environment_options.only` is set.

Common situations: Scripts or CI pipelines that always append `--clear-database` to publish invocations, then get an `--env-only` flag added for env-only redeploys; copy-pasting both flags from different runbooks.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• Aborted.
• AddColumns: table ` ` not found in new module def
• AddConstraint: ` ` not found in new module def
• AddRowLevelSecurity: RLS
• AddSequence: ` ` not found in new module def

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

Appendix: source

Thrown at crates/cli/src/subcommands/publish.rs:595

async fn execute_publish_configs<'a>(
    config: &mut Config,
    publish_configs: Vec<CommandConfig<'a>>,
    using_config: bool,
    config_dir: Option<&std::path::Path>,
    clear_database: ClearMode,
    yes: YesFlags,
    environment_options: &EnvironmentOptions,
) -> Result<(), anyhow::Error> {
    // Execute publish for each config
    for command_config in publish_configs {
        // Get values using command_config.get_one() which merges CLI + config
        let server_opt = command_config.get_one::<String>("server")?;
        let server = server_opt.as_deref();
        let name_or_identity_opt = command_config.get_one::<String>("database")?;
        let name_or_identity = name_or_identity_opt.as_deref();
        let anon_identity = command_config.get_one::<bool>("anon_identity")?.unwrap_or(false);
        if environment_options.only {
            ensure!(clear_database == ClearMode::Never, "--env-only cannot reset a database");
            environment::publish_only(
                config,
                server,
                name_or_identity.context("--env-only requires an existing database name or identity")?,
                anon_identity,
                yes,
                command_config.get_config_value("env"),
                environment_options,
            )
            .await?;
            continue;
        }
        let wasm_file = command_config.get_one::<PathBuf>("wasm_file")?;
        let js_file = command_config.get_one::<PathBuf>("js_file")?;
        let resolved_module_path = command_config.get_resolved_path("module_path", config_dir)?;
        let path_to_project = if wasm_file.is_some() || js_file.is_some() {
            resolved_module_path
        } else {

View on GitHub (pinned to eddf9f5014)