clockworklabs/SpacetimeDB · error

Environment key is absent

Error message

Environment key is absent

What it means

Thrown by `render` in the `Query::Get(_)` branch when a get-single-key environment read returns zero rows instead of exactly one. The key you asked for does not exist in the environment, so there is no value to print.

Solutions

1. Run `spacetime env list` to see which keys actually exist.
2. Check the key spelling and case exactly.
3. Confirm you targeted the same database/identity where the key was set.
4. Set the key first with `spacetime env set KEY value` if it is missing.

Example fix

// before
spacetime env get API_KEY   # Environment key is absent
// after
spacetime env list          # shows api_key exists
spacetime env get api_key

// verify the key exists before `env get`
let list = cmd("spacetime env list")?;
if !list.contains(key) { return Err(format!("{key} not set")); }

match env_get(key) {
    Err(e) if e.to_string().contains("Environment key is absent") => {
        // fall back to a default value or set the key
    }
    other => other?,
}

When it happens

Trigger: `spacetime env get KEY` executes successfully but `result.rows.len() == 0` — the key was never set, was already unset, or the query targeted a different database/environment than the one where the key exists.

Common situations: Typo in the key name; key set on a different database; key removed by another developer or a deploy with `--unset-env`; case-sensitivity mismatch in the key.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Environment key count exceeds limit
• Environment read failed with HTTP
• Environment read value exceeds limit
• Cannot extract accessor name from query
• Cannot extract table name from query

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

Appendix: source

Thrown at crates/cli/src/subcommands/env.rs:162

            "Environment read value exceeds limit"
        );
    }
    match query {
        Query::List => {
            let mut rows: Vec<_> = result.rows.iter().collect();
            rows.sort_unstable_by(|a, b| a[0].cmp(&b[0]));
            let rows = rows.into_iter().map(|row| {
                Ok::<_, std::convert::Infallible>(spacetimedb_lib::sats::product![row[0].as_str(), row[1].as_str()])
            });
            let table = sql::build_table(
                spacetimedb_lib::sats::satn::PsqlClient::SpacetimeDB,
                &result.schema,
                rows,
            )?;
            Ok(format!("{table}\n"))
        }
        Query::Get(_) => {
            ensure!(result.rows.len() == 1, "Environment key is absent");
            Ok(format!("{}\n", result.rows[0][0]))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    fn body(columns: &[&'static str], rows: Vec<Vec<&str>>) -> Vec<u8> {
        serde_json::to_vec(&[spacetimedb_client_api_messages::http::SqlStmtResult {
            schema: spacetimedb_lib::sats::ProductType::from_iter(
                columns
                    .iter()
                    .map(|column| (*column, spacetimedb_lib::AlgebraicType::String)),
            ),
            rows,
            total_duration_micros: 0,
            stats: Default::default(),

View on GitHub (pinned to eddf9f5014)