clockworklabs/SpacetimeDB · error

--replace-env cannot be combined with --unset-env

Error message

--replace-env cannot be combined with --unset-env

What it means

The CLI's `validate_values` (called from `publication_body` in the publish flow) rejects an EnvironmentOptions where `--replace-env` is set while `--unset-env` is non-empty. Replacing all environment values and simultaneously removing individual keys is contradictory: after a full replace there is nothing left to unset, and the two flags would fight over the final value set. The check uses `ensure!` so it fires before any network request is made.

Solutions

1. Use only `--replace-env` (supply the full final set of values; omitted keys are effectively unset).
2. Alternatively drop `--replace-env` and use `--unset-env KEY` to remove just the specific keys.
3. If both behaviors are needed across steps, run two publish calls: one to unset keys, one to replace values.

Example fix

// before
spacetime publish --replace-env --unset-env MY_SECRET -d mydb
// after (replace env; omit the key instead of unsetting it)
spacetime publish --replace-env OTHER=value -d mydb

// bash pre-check before invoking publish
if grep -q -- '--replace-env' args.txt && grep -q -- '--unset-env' args.txt; then
  echo "Refusing: --replace-env and --unset-env are mutually exclusive"; exit 1;
fi

When it happens

Trigger: Running `spacetime publish` with both `--replace-env` and one or more `--unset-env KEY` flags; programmatically constructing EnvironmentOptions with `replace=true` and a non-empty `remove` BTreeMap and passing it to publication_body/execute_publish_configs.

Common situations: Developers cleaning up environment configuration who want to start fresh (`--replace-env`) but also clear one specific leftover key with `--unset-env`; scripts that append flags conditionally and end up passing both.

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

• Environment key is both supplied and removed
• Invalid environment key name
• Cannot read environment schema: HTTP
• database is a required field in publish config
• Either --out-dir or --uproject-dir is required

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

Appendix: source

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

            only: args.get_flag("env_only"),
            remove: args
                .get_many::<String>("unset_env")
                .map(|keys| keys.cloned().collect())
                .unwrap_or_default(),
            replace: args.get_flag("replace_env"),
        };
        ensure!(
            options.remove.len() <= spacetimedb_lib::environment::MAX_ENV_VARS,
            "Too many environment removals"
        );
        for key in &options.remove {
            spacetimedb_lib::environment::validate_key(key)?;
        }
        Ok(options)
    }

    fn validate_values(&self, values: &std::collections::BTreeMap<String, String>) -> anyhow::Result<()> {
        ensure!(
            !self.replace || self.remove.is_empty(),
            "--replace-env cannot be combined with --unset-env"
        );
        for key in &self.remove {
            ensure!(
                !values.contains_key(key),
                "Environment key {key:?} is both supplied and removed"
            );
        }
        Ok(())
    }
}

fn publication_body(
    module: &spacetimedb_schema::def::ModuleDef,
    bytes: Vec<u8>,
    environment: std::collections::BTreeMap<String, String>,
    options: &EnvironmentOptions,

View on GitHub (pinned to eddf9f5014)