{"record":{"id":"64ba86a6c42b51d5","repo":"clockworklabs/SpacetimeDB","slug":"required-environment-key-is-missing","errorCode":null,"errorMessage":"required environment key is missing: {}","messagePattern":"required environment key is missing: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/bindings-macro/src/environment/value.rs","lineNumber":90,"sourceCode":"        [value] => quote!(::spacetimedb::spacetimedb_lib::environment::EnvVarType::StringLiteral(#value.into())),\n        values => quote!(::spacetimedb::spacetimedb_lib::environment::EnvVarType::Union(\n            ::std::vec![#(#values.into()),*]\n        )),\n    };\n    let ident = &item.ident;\n    Ok(quote! {\n        impl ::spacetimedb::rt::EnvironmentValue for #ident {\n            const OPTIONAL: bool = false;\n\n            fn constraint() -> ::spacetimedb::spacetimedb_lib::environment::EnvVarType {\n                #constraint\n            }\n\n            fn from_environment(value: ::std::option::Option<::std::string::String>, key: &str) -> Self {\n                match value.as_deref() {\n                    #(::std::option::Option::Some(#values) => Self::#variants,)*\n                    ::std::option::Option::Some(_) => ::core::panic!(\"environment value does not match its declared enum: {}\", key),\n                    ::std::option::Option::None => ::core::panic!(\"required environment key is missing: {}\", key),\n                }\n            }\n        }\n        impl ::spacetimedb::rt::RequiredEnvironmentValue for #ident {}\n    })\n}\n\n#[cfg(test)]\nmod tests {\n    use super::*;\n\n    #[test]\n    fn rejects_invalid_enum_shapes_mappings_and_limits() {\n        for input in [\n            quote!(\n                struct Value;\n            ),\n            quote!(","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/bindings-macro/src/environment/value.rs#L72-L108","documentation":"For RequiredEnvironmentValue types, the generated from_environment panics when the environment lookup returns None — i.e. the required key is absent from the process environment. The derive treats the variable as mandatory, so startup aborts with this message naming the key.","triggerScenarios":"Running a SpacetimeDB module whose derived required environment type cannot find its key in the host-provided environment, e.g. the variable was never set in the deployment config.","commonSituations":"Forgetting to add the variable to the deployment environment/secrets; a typo in the key between the module declaration and the .env or platform config; renaming the key in code without updating ops configuration.","solutions":["Set the required environment key in the module's deployment environment","Fix the key name so it matches the declared identifier exactly","Switch the derive/type to an optional value if the variable is genuinely optional"],"exampleFix":"// before\n# .env\n# API_KEY missing\n// after\n# .env\nAPI_KEY=abcd1234","handlingStrategy":"try-catch","validationCode":"for key in [\"API_KEY\", \"DB_URL\"] {\n    if std::env::var(key).is_err() {\n        eprintln!(\"missing required env key: {key}\");\n    }\n}","typeGuard":null,"tryCatchPattern":"// panic! cannot be caught; fail fast with your own preflight check:\nfn preflight(required: &[&str]) -> Result<(), String> {\n    let missing: Vec<_> = required.iter().filter(|k| std::env::var(k).is_err()).collect();\n    if missing.is_empty() { Ok(()) } else { Err(format!(\"missing: {missing:?}\")) }\n}","preventionTips":["Add a startup preflight that checks all required keys before module init","Keep the .env / deployment secret list in sync with declared keys","Use identical key spellings between code and ops configuration"],"tags":["environment","rust","macro","panic","missing-config"],"backgroundTag":"missing-env-var","analyzedSha":"eddf9f5014579a50d4b67630e28b6e15cad9c4af","analyzedAt":"2026-09-20T12:15:59.611Z","contentChangedAt":"2026-09-20T12:15:59.611Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}