unicity-aos/aos-ce · error · std::io::Error

cannot contain a platform PATH separator

Error message

{variable} cannot contain a platform PATH separator

What it means

validate_path_entry wraps std::env::join_paths, which fails when a single path entry contains the platform's PATH separator (':' on Unix, ';' on Windows); the library converts that failure into this io::Error (InvalidInput). Since the value will be placed into a PATH-like environment variable, an embedded separator would be silently split into multiple bogus entries, so it is rejected up front.

Solutions

1. Remove the platform PATH separator from the variable's value: it must be exactly one path.
2. On Windows code paths, use a Windows path (drive letter + backslashes); on Unix, avoid pasted Windows paths with drive letters or semicolons.
3. If you need multiple locations, use the variable intended for a list of paths instead of a single-path variable.
4. Echo the variable and check for ':' (Unix) or ';' (Windows) before launching.

Example fix

// before
export AOS_HOME="/opt/aos:/opt/aos2"
// after
export AOS_HOME="/opt/aos"

fn valid_single_path_entry(v: &str) -> bool {
    let sep = if cfg!(windows) { ';' } else { ':' };
    !v.is_empty() && !v.contains(sep)
}
if !valid_single_path_entry(&value) {
    return Err("the variable must contain exactly one path with no PATH separator");
}

match result {
    Err(e) if e.kind() == std::io::ErrorKind::InvalidInput && e.to_string().contains("PATH separator") => {
        eprintln!("fix the environment variable: it must be a single path without ':' or ';'");
    }
    other => other?,
}

When it happens

Trigger: Calling validated_environment_root (which validates each candidate path via validate_path_entry) when the env variable's value (e.g. AOS_HOME or similar) contains ':' or ';' — typically because a Windows-style 'C:\...' string was pasted into a Unix environment, or a list of paths was assigned to a variable that expects exactly one path.

Common situations: Setting AOS_HOME='C:\Users\me\aos' on Linux/macOS; quoting or copying a PATH-style value into a single-value variable; Windows/Unix environment drift in WSL or CI where PATH-formatted values are reused.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• must be an absolute path
• bundled executable must have a parent directory
• canonical document exceeds bound
• must not be empty
• cannot construct the bundled runtime PATH

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/c33a356c1759eb36. Report an issue: GitHub.

Appendix: source

Thrown at crates/unicity-aos-bootstrap/src/lib.rs:581

            format!(
                "AOS managed path must be a real directory: {}",
                path.display()
            ),
        ));
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        fs::set_permissions(path, fs::Permissions::from_mode(0o700))?;
    }
    Ok(())
}

fn validate_path_entry(path: &Path, variable: &str) -> io::Result<()> {
    std::env::join_paths(std::iter::once(path))
        .map(drop)
        .map_err(|_| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                format!("{variable} cannot contain a platform PATH separator"),
            )
        })
}

fn set_private_file_permissions(path: &Path) -> io::Result<()> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        fs::set_permissions(path, fs::Permissions::from_mode(0o600))?;
    }
    #[cfg(not(unix))]
    let _ = path;
    Ok(())
}

#[cfg(windows)]

View on GitHub (pinned to f6f22024fb)