unicity-aos/aos-ce · error · std::io::Error
must not be empty
Error message
{variable} must not be empty What it means
validated_environment_root rejects an empty OsString root with an InvalidInput io error formatted as "{variable} must not be empty", where {variable} is the environment variable name being read. It is the first of several validations applied to root-directory environment variables before the value is turned into a PathBuf.
Solutions
- Set the environment variable to a non-empty absolute path before launching the process.
- Provide a sensible default in code when the variable is empty or missing.
- Fail fast at startup with a clear message naming the variable so operators fix the environment, not the code.
Example fix
// before
let root = std::env::var_os("MYAPP_ROOT").unwrap_or_default();
let root = validated_environment_root(root, "MYAPP_ROOT")?;
// after
let root = match std::env::var_os("MYAPP_ROOT") {
Some(v) if !v.is_empty() => v,
_ => return Err("MYAPP_ROOT must be set to an absolute path".into()),
};
let root = validated_environment_root(root, "MYAPP_ROOT")?; Defensive patterns
Strategy: validation
Validate before calling
fn require_non_empty_env(name: &str) -> Result<OsString, String> {
match std::env::var_os(name) {
Some(v) if !v.is_empty() => Ok(v),
Some(_) => Err(format!("{name} is set but empty")),
None => Err(format!("{name} is not set")),
}
} Try / catch
match validated_environment_root(root, "MYAPP_ROOT") {
Err(e) if e.kind() == io::ErrorKind::InvalidInput && e.to_string().contains("must not be empty") => {
eprintln!("MYAPP_ROOT is empty; set it to an absolute path");
}
other => other?,
} Prevention
- In shell launchers use ${VAR:?msg} to abort on unset/empty variables before exec.
- Validate all required environment variables once at process startup with a single check function.
- In CI, mark required secret/variable fields as mandatory so they cannot be saved blank.
When it happens
Trigger: Reading a root-directory environment variable whose value is set but empty (e.g. export FOO_ROOT=) and passing it to validated_environment_root via the wrapper that formats the error with the variable name.
Common situations: An unset variable expanded to empty string in a shell script; a CI secret defined but left blank; a systemd unit or Dockerfile ENV that sets the variable to ""; a profile file exporting VAR= with no value.
Understand the failure class
Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.
Related errors
- must be an absolute path
- canonical document exceeds bound
- bundled executable must have a parent directory
- cannot construct the bundled runtime PATH
- AOS managed path must be a real directory
AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13).
Data as JSON: /api/errors/fa844603e15200a6.
Report an issue: GitHub.
Appendix: source
Thrown at crates/unicity-aos-bootstrap/src/lib.rs:92
{
if let Some(root) = get("AOS_HOME") {
return Self::from_environment_root(root, "AOS_HOME");
}
let home = default_home(&get)?;
let home = Self::validated_environment_root(home, default_home_name())?;
Ok(Self::from_root(home.join(".aos")))
}
fn from_environment_root(root: OsString, variable: &str) -> io::Result<Self> {
Ok(Self::from_root(Self::validated_environment_root(
root, variable,
)?))
}
fn validated_environment_root(root: OsString, variable: &str) -> io::Result<PathBuf> {
if root.is_empty() {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
format!("{variable} must not be empty"),
));
}
let root = PathBuf::from(root);
if !root.is_absolute() {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
format!("{variable} must be an absolute path"),
));
}
validate_path_entry(&root, variable)?;
Ok(root)
}
/// Build an AOS home from an explicit root, useful for embedding and tests.
#[must_use]View on GitHub (pinned to f6f22024fb)