{"record":{"id":"5c18133ba3d17a68","repo":"astrid-runtime/astrid","slug":"astrid-workspace-state-dir-must-be-valid-utf-8","errorCode":null,"errorMessage":"ASTRID_WORKSPACE_STATE_DIR must be valid UTF-8","messagePattern":"ASTRID_WORKSPACE_STATE_DIR must be valid UTF-8","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-daemon/src/lib.rs","lineNumber":212,"sourceCode":"/// binary and the `astrid` CLI's bundled daemon binary.\n///\n/// # Errors\n///\n/// Returns an error if the kernel fails to boot, the native local uplink cannot\n/// claim its listener, or the readiness file cannot be written.\n#[cfg(unix)]\n#[expect(\n    clippy::too_many_lines,\n    reason = \"boot sequence: sequential config resolution + kernel/capsule setup that does not benefit from splitting\"\n)]\npub async fn run() -> Result<()> {\n    let args = Args::parse();\n    let workspace_layout = match std::env::var(\"ASTRID_WORKSPACE_STATE_DIR\") {\n        Ok(value) => astrid_core::dirs::WorkspaceLayout::new(value)\n            .context(\"invalid ASTRID_WORKSPACE_STATE_DIR\")?,\n        Err(std::env::VarError::NotPresent) => astrid_core::dirs::WorkspaceLayout::default(),\n        Err(std::env::VarError::NotUnicode(_)) => {\n            anyhow::bail!(\"ASTRID_WORKSPACE_STATE_DIR must be valid UTF-8\")\n        },\n    };\n    let astrid_home =\n        astrid_core::dirs::AstridHome::resolve().context(\"Failed to resolve Astrid home\")?;\n\n    let workspace_root = args.workspace.clone().unwrap_or_else(|| {\n        std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from(\".\"))\n    });\n\n    // Load the unified config once: it drives both logging and the capsule\n    // runtime concurrency ceilings below.\n    let unified_cfg = astrid_config::Config::load_with_home_and_layout(\n        Some(&workspace_root),\n        astrid_home.root(),\n        &workspace_layout,\n    )\n    .ok()\n    .map(|r| r.config);","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-daemon/src/lib.rs#L194-L230","documentation":"`run` reads ASTRID_WORKSPACE_STATE_DIR from the environment and requires it to be valid UTF-8 before constructing a WorkspaceLayout. If the variable is set but contains non-Unicode bytes, the daemon cannot turn it into a Rust String/path safely and bails with this error instead of silently mangling the path.","triggerScenarios":"Starting the daemon with ASTRID_WORKSPACE_STATE_DIR set to bytes that are not valid UTF-8 (e.g. raw Latin-1 filenames, shell mangling from a corrupted script, binary garbage in the environment).","commonSituations":"Environments assembled on systems with non-UTF-8 locale/filenames; env vars copied through tools that transcode incorrectly; paths containing emoji/legacy encodings on filesystems that don't enforce UTF-8.","solutions":["Unset ASTRID_WORKSPACE_STATE_DIR to use the default workspace layout.","Re-set the variable with a valid UTF-8 path: `export ASTRID_WORKSPACE_STATE_DIR=/home/user/.astrid/state`.","Inspect the raw bytes (`env | grep -a ASTRID_WORKSPACE_STATE_DIR | od -c`) and fix the source that wrote them.","Fix the script/exporter that injects the variable so it emits UTF-8."],"exampleFix":"// before\nexport ASTRID_WORKSPACE_STATE_DIR=$(printf '\\xff\\xfe/state')   # invalid bytes\n// after\nexport ASTRID_WORKSPACE_STATE_DIR=\"$HOME/.astrid/state\"        # valid UTF-8","handlingStrategy":"validation","validationCode":"fn workspace_state_dir_is_utf8() -> bool {\n    match std::env::var(\"ASTRID_WORKSPACE_STATE_DIR\") {\n        Err(std::env::VarError::NotPresent) => true,\n        Ok(_) => true,\n        Err(std::env::VarError::NotUnicode(_)) => false,\n    }\n}","typeGuard":null,"tryCatchPattern":"match daemon_run() {\n    Err(e) if e.to_string().contains(\"must be valid UTF-8\") => {\n        eprintln!(\"{e:#}; unset ASTRID_WORKSPACE_STATE_DIR or re-export with a UTF-8 path\");\n        std::process::exit(1);\n    }\n    other => other,\n}","preventionTips":["Always export the variable from UTF-8-safe sources (`printf '%s'`, not raw bytes).","Check env bytes with `env | grep -a VAR | od -c` when debugging encoding issues.","Unset the variable to fall back to the default workspace layout.","Ensure build/CI environments use a UTF-8 locale (LANG=C.UTF-8)."],"tags":["daemon","environment","encoding","utf8"],"backgroundTag":"invalid-env-var-value","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}