{"record":{"id":"74200156535613ae","repo":"jdx/mise","slug":"the-prefix-cannot-be-printed-as-a-single-utf-8-path-use-a-742001","errorCode":null,"errorMessage":"the prefix cannot be printed as a single UTF-8 path; use a compatible prefix path","messagePattern":"the prefix cannot be printed as a single UTF-8 path; use a compatible prefix path","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/system/packages/brew/pour.rs","lineNumber":52,"sourceCode":"/// without it is a remnant of a failed install and must not block a retry.\npub(super) fn keg_installed(name: &str, pkg_version: &str) -> bool {\n    keg_path(name, pkg_version).exists() && linked_version(name).as_deref() == Some(pkg_version)\n}\n\n/// the version `opt/<name>` points at, if the symlink resolves to an\n/// existing keg\npub(super) fn linked_version(name: &str) -> Option<String> {\n    let opt = prefix::prefix().join(\"opt\").join(name);\n    record_keg(name, &opt).map(|(version, _)| version)\n}\n\n/// Return the absolute opt path only when its symlink resolves to a keg directly inside the formula rack.\n/// Preserve the configured prefix spelling and report invalid records without repairing them.\npub(super) fn strict_package_root(name: &str) -> Result<PathBuf> {\n    if let Some(prefix) = std::env::var_os(\"MISE_SYSTEM_BREW_PREFIX\")\n        && prefix.to_str().is_none()\n    {\n        bail!(\"the prefix cannot be printed as a single UTF-8 path; use a compatible prefix path\");\n    }\n    let prefix = prefix::prefix();\n    let prefix = if prefix.is_absolute() {\n        prefix\n    } else {\n        std::env::current_dir()\n            .wrap_err_with(|| {\n                format!(\n                    \"cannot resolve relative Homebrew prefix {}\",\n                    prefix.display()\n                )\n            })?\n            .join(prefix)\n    };\n    let opt = prefix.join(\"opt\").join(name);\n    let rack = prefix.join(\"Cellar\").join(name);\n    let metadata =\n        std::fs::symlink_metadata(&opt).map_err(|err| package_root_io_error(name, &opt, err))?;","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/system/packages/brew/pour.rs#L34-L70","documentation":"strict_package_root validates the `opt/<name>` record for an installed brew formula. It first checks that MISE_SYSTEM_BREW_PREFIX, when set, is representable as UTF-8, because the prefix path must be printable and passed to subprocesses/paths as a Rust str-backed Path. If the environment variable contains bytes that are not valid UTF-8 (e.g. invalid UTF-8 from a shell env), mise bails instead of guessing an encoding.","triggerScenarios":"Setting MISE_SYSTEM_BREW_PREFIX to a value with non-UTF-8 bytes (e.g. via `env -i` scripts, raw byte export, or copy-pasted control characters) and then invoking anything that calls strict_package_root to resolve a package root.","commonSituations":"Container/CI images exporting env vars built from binary data; shells with locale mishandling producing invalid UTF-8 paths; accidentally setting the variable to a command's binary output.","solutions":["Unset or correct MISE_SYSTEM_BREW_PREFIX so it contains a valid UTF-8 absolute path (e.g. /home/linuxbrew/.linuxbrew)","Print the variable to check it: `printf '%s' \"$MISE_SYSTEM_BREW_PREFIX\" | iconv -f utf-8 -t utf-8` — failure confirms invalid bytes","Remove the override entirely to let mise use the default prefix"],"exampleFix":"// before\nexport MISE_SYSTEM_BREW_PREFIX=$'\\xff/home/brew'  # invalid UTF-8\n// after\nexport MISE_SYSTEM_BREW_PREFIX=/home/linuxbrew/.linuxbrew","handlingStrategy":"validation","validationCode":"if (process.env.MISE_SYSTEM_BREW_PREFIX !== undefined) {\n  Buffer.from(process.env.MISE_SYSTEM_BREW_PREFIX, 'utf8'); // throws on invalid encoding\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set MISE_SYSTEM_BREW_PREFIX from a literal or command substitution of a plain path","Verify env exports in provisioning scripts don't capture binary output","Keep provisioning scripts in UTF-8-safe shells/locales"],"tags":["brew","env","utf-8"],"backgroundTag":"invalid-env-var-value","analyzedSha":"533346cc374382b41ec5ff70536252b2e96e725c","analyzedAt":"2026-09-17T13:35:38.149Z","contentChangedAt":"2026-09-17T13:35:38.149Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}