What causes "environment value does not match its declared enum: {}" in clockworklabs/SpacetimeDB?

Set the environment variable to exactly one of the declared variant strings (case-sensitive)

environment value does not match its declared enum

Error message

environment value does not match its declared enum: {}

What it means

This macro-generated from_environment implementation panics at runtime when the actual environment value is Some(s) but s does not match any of the enum's declared variant strings. The type's accepted strings are an exact, closed set, so any other value is unrecoverable for that attribute.

Solutions

Set the environment variable to exactly one of the declared variant strings (case-sensitive)
Update the enum to include the value being supplied
Trim whitespace and fix casing in the .env file or process environment

Example fix

// before
MODE=production  # enum variant is 'Production'
// after
MODE=Production

Defensive patterns

Strategy: try-catch

Validate before calling

const ALLOWED_MODES = ["Production", "Staging", "Dev"];
let mode = std::env::var("MODE").unwrap_or_default();
assert!(ALLOWED_MODES.contains(&mode.as_str()), "MODE={mode} not in {ALLOWED_MODES:?}");

Try / catch

// panic! is not catchable; validate before the library parses the value:
match std::env::var("MODE") {
  Ok(v) if matches!(v.as_str(), "Production" | "Staging" | "Dev") => {}
  Ok(v) => eprintln!("MODE={v} not allowed"),
  Err(_) => eprintln!("MODE unset"),
}

Prevention

Keep an allowlist of exact accepted strings next to the deployment config
Trim whitespace in .env files and avoid case drift
Update deployment env in lockstep with enum variant renames

When it happens

Trigger: A process environment variable is set to a value that is not one of the enum's exact variant strings (case-sensitive) when the derived type is parsed via accepts_exact_strings_and_ordinary_enum_attributes.

Common situations: Setting MODE=production when the enum only accepts 'Production'; typos, trailing whitespace, or lowercase values in .env files; renamed enum variants after a version upgrade while the host still exports the old value.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at crates/bindings-macro/src/environment/value.rs:89

    let constraint = match values.as_slice() {
        [value] => quote!(::spacetimedb::spacetimedb_lib::environment::EnvVarType::StringLiteral(#value.into())),
        values => quote!(::spacetimedb::spacetimedb_lib::environment::EnvVarType::Union(
            ::std::vec![#(#values.into()),*]
        )),
    };
    let ident = &item.ident;
    Ok(quote! {
        impl ::spacetimedb::rt::EnvironmentValue for #ident {
            const OPTIONAL: bool = false;

            fn constraint() -> ::spacetimedb::spacetimedb_lib::environment::EnvVarType {
                #constraint
            }

            fn from_environment(value: ::std::option::Option<::std::string::String>, key: &str) -> Self {
                match value.as_deref() {
                    #(::std::option::Option::Some(#values) => Self::#variants,)*
                    ::std::option::Option::Some(_) => ::core::panic!("environment value does not match its declared enum: {}", key),
                    ::std::option::Option::None => ::core::panic!("required environment key is missing: {}", key),
                }
            }
        }
        impl ::spacetimedb::rt::RequiredEnvironmentValue for #ident {}
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rejects_invalid_enum_shapes_mappings_and_limits() {
        for input in [
            quote!(
                struct Value;
            ),

View on GitHub (pinned to eddf9f5014)