{"record":{"id":"cbeda6f5d89e6551","repo":"clockworklabs/SpacetimeDB","slug":"environment-key-shell-input-must-be-utf-8","errorCode":null,"errorMessage":"Environment key {:?}: shell input must be UTF-8","messagePattern":"Environment key (.+?): shell input must be UTF-8","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/cli/src/subcommands/publish/environment.rs","lineNumber":68,"sourceCode":"        let config = config.as_object().context(\"Environment config must be an object\")?;\n        for (name, value) in config {\n            spacetimedb_lib::environment::validate_key(name)?;\n            let value = match value {\n                Value::String(value) => value.clone(),\n                Value::Bool(value) => value.to_string(),\n                Value::Number(value) => value.to_string(),\n                _ => anyhow::bail!(\"Environment key {name:?}: config input must be a string, boolean or JSON number\"),\n            };\n            resolved.values.insert(name.clone(), value);\n            resolved.sources.insert(name.clone(), Source::Config);\n        }\n    }\n    // Lookup only the new artifact's declared names, never enumerate ambient values.\n    for declaration in schema.declarations() {\n        if let Some(value) = shell(&declaration.name) {\n            let value = value\n                .into_string()\n                .map_err(|_| anyhow::anyhow!(\"Environment key {:?}: shell input must be UTF-8\", declaration.name))?;\n            resolved.values.insert(declaration.name.clone(), value);\n            resolved.sources.insert(declaration.name.clone(), Source::Shell);\n        }\n    }\n    schema.validate_supplied_values(&resolved.values)?;\n    Ok(resolved)\n}\n\n#[cfg(test)]\nmod tests;\n\n/// Update configuration without inspecting or building a local module.\npub(super) async fn publish_only(\n    config: &mut crate::config::Config,\n    server: Option<&str>,\n    database: &str,\n    anonymous: bool,\n    yes: super::YesFlags,","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/cli/src/subcommands/publish/environment.rs#L50-L86","documentation":"During `resolve` of environment values, the CLI looks up each declared key in the shell environment. If a value is found but cannot be converted to a UTF-8 `String` (it contains invalid bytes, e.g. non-UTF-8 locale data), `into_string()` fails and this error names the offending key. SpacetimedDB environment values must be valid UTF-8 strings.","triggerScenarios":"An environment variable declared by the module contains raw bytes that are not valid UTF-8 (e.g. binary data or a non-UTF-8 encoded value); `std::env::var_os` yields an OsString whose `into_string()` fails.","commonSituations":"Locales using legacy encodings (e.g. Latin-1) exporting variables with accented characters encoded in non-UTF-8; secrets or tokens pasted from binary sources; variables set by tooling with escaped byte sequences.","solutions":["Re-set the offending environment variable with valid UTF-8 content before publishing.","Check encoding: run `locale` and switch to a UTF-8 locale (e.g. `export LANG=C.UTF-8`).","Identify bad bytes with `printf '%s' \"$KEY\" | xxd` and fix the source of the value.","If the variable shouldn't be picked up from the shell, unset it or supply the value via `--env` instead."],"exampleFix":"// before (shell)\nexport API_TOKEN=$'caf\\xe9'   # Latin-1 bytes\nspacetime publish -d mydb     # Environment key \"API_TOKEN\": shell input must be UTF-8\n// after\nexport API_TOKEN='café'       # UTF-8 encoded\nspacetime publish -d mydb","handlingStrategy":"validation","validationCode":"// bash: fail early if any declared var is not valid UTF-8\nfor k in \"$@\"; do\n  printf '%s' \"${!k}\" | iconv -f UTF-8 -t UTF-8 >/dev/null || { echo \"$k is not UTF-8\"; exit 1; }\ndone","typeGuard":null,"tryCatchPattern":"// rust: pre-validate env values you inject\nfn assert_utf8(key: &str) -> anyhow::Result<()> {\n    std::env::var_os(key)\n        .map(|v| v.into_string().map_err(|_| anyhow::anyhow!(\"{key} not UTF-8\")))\n        .unwrap_or(Ok(()))\n}","preventionTips":["Use UTF-8 locales (LANG/LC_ALL=C.UTF-8) in CI and shells that set module env vars.","Never store binary data in environment variables consumed by modules.","Re-encode values coming from legacy systems before exporting them."],"tags":["environment","encoding","utf-8","cli"],"backgroundTag":"invalid-env-var-value","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"}