{"record":{"id":"cf282fdf79e5ffdc","repo":"astrid-runtime/astrid","slug":"astrid-enforced-distro-must-contain-a-valid-utf-8","errorCode":null,"errorMessage":"ASTRID_ENFORCED_DISTRO must contain a valid UTF-8 distro source","messagePattern":"ASTRID_ENFORCED_DISTRO must contain a valid UTF-8 distro source","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/astrid-cli/src/dispatch.rs","lineNumber":277,"sourceCode":"}\n\nfn resolve_init_distro(requested: Option<String>) -> Result<String> {\n    resolve_init_distro_with(requested, std::env::var_os(\"ASTRID_ENFORCED_DISTRO\"))\n}\n\nfn resolve_init_distro_with(\n    requested: Option<String>,\n    enforced: Option<OsString>,\n) -> Result<String> {\n    let Some(enforced) = enforced else {\n        return non_empty_distro_source(requested).ok_or_else(|| {\n            anyhow::anyhow!(\n                \"astrid init requires --distro <@owner/repo, URL, local Distro.toml, or .shuttle> unless ASTRID_ENFORCED_DISTRO is set by an embedding launcher; Astrid Runtime does not choose a product distro\"\n            )\n        });\n    };\n    let enforced = enforced.into_string().map_err(|_| {\n        anyhow::anyhow!(\"ASTRID_ENFORCED_DISTRO must contain a valid UTF-8 distro source\")\n    })?;\n    if enforced.is_empty() {\n        anyhow::bail!(\"ASTRID_ENFORCED_DISTRO must not be empty\");\n    }\n    if requested.is_some() {\n        anyhow::bail!(\n            \"astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO\"\n        );\n    }\n    Ok(enforced)\n}\n\nfn non_empty_distro_source(source: Option<String>) -> Option<String> {\n    source.filter(|source| !source.is_empty())\n}\n\n/// Route the root capsule-verb shorthand (`astrid <verb> [args…]`).\n///","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/dispatch.rs#L259-L295","documentation":"Validation guard in cargo_config_includes: a Cargo config [include] entry used the table form but its 'path' key is missing or not a string, so the include cannot be resolved while loading build content.","triggerScenarios":"resolve_init_distro_with calls enforced.into_string() on the OsString from the environment and it contains non-UTF-8 bytes (e.g. invalid encoding injected by a launcher or shell).","commonSituations":"A launcher writing the env var from non-UTF-8 binary data; locale/encoding mismatches on exotic systems; corrupted shell profiles exporting broken bytes.","solutions":["Unset and re-export ASTRID_ENFORCED_DISTRO with plain ASCII/UTF-8 content","Fix the embedding launcher to write valid UTF-8 into the variable","Check shell profiles/CI config for stray binary characters","echo -n \"$ASTRID_ENFORCED_DISTRO\" | iconv -f utf-8 -t utf-8 to verify validity"],"exampleFix":"// before\nexport ASTRID_ENFORCED_DISTRO=$'\\xff@owner/repo'\n// after\nexport ASTRID_ENFORCED_DISTRO='@owner/repo'","handlingStrategy":"validation","validationCode":"match std::env::var_os(\"ASTRID_ENFORCED_DISTRO\") {\n    Some(v) if v.to_str().is_none() => eprintln!(\"ASTRID_ENFORCED_DISTRO is not valid UTF-8\"),\n    _ => {}\n}","typeGuard":"fn enforced_distro_valid() -> bool {\n    std::env::var_os(\"ASTRID_ENFORCED_DISTRO\")\n        .map(|v| v.to_string().ok().map(|s| !s.is_empty()).unwrap_or(false))\n        .unwrap_or(true)\n}","tryCatchPattern":"match resolve_init_distro(requested) {\n    Err(e) if e.to_string().contains(\"valid UTF-8\") => eprintln!(\"re-export ASTRID_ENFORCED_DISTRO with UTF-8 content\"),\n    other => other?,\n}","preventionTips":["Export env vars from plain ASCII shell content","Validate launcher-written env vars early","Avoid binary interpolation into exported variables"],"tags":["env-var","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"}