Cannot determine current username; ACL hardening is required

Error message

Cannot determine current username; ACL hardening is required for key file protection

What it means

On Windows, before any key byte hits disk, apply_windows_acl must build a restrictive grant for the current user, which requires knowing the username: it runs `whoami`, falling back to the USERNAME env var. If both fail (whoami errors or outputs failure, and USERNAME is unset/empty — e.g., stripped service contexts), the grant argument cannot be built and the function fails closed: key publication aborts rather than writing a key with inherited (looser) ACLs. Reached from write_key_file_atomic_publish_with during first-run key creation.

Source

Thrown at crates/zeroclaw-config/src/secrets.rs:839

/// ACLs.  Fail-closed: if hardening cannot be established, publication aborts
/// so the key is never visible with unhardened permissions.
#[cfg(windows)]
fn apply_windows_acl(path: &Path) -> Result<()> {
    let username = std::process::Command::new("whoami")
        .output()
        .ok()
        .filter(|o| o.status.success())
        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
        .unwrap_or_else(|| std::env::var("USERNAME").unwrap_or_default());
    let Some(grant_arg) = build_windows_icacls_grant_arg(&username) else {
        ::zeroclaw_log::record!(
            WARN,
            ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Note)
                .with_outcome(::zeroclaw_log::EventOutcome::Unknown),
            "USERNAME environment variable is empty; \
             cannot restrict key file permissions via icacls"
        );
        anyhow::bail!(
            "Cannot determine current username; \
             ACL hardening is required for key file protection"
        );
    };

    match std::process::Command::new("takeown")
        .arg("/F")
        .arg(path)
        .output()
    {
        Ok(o) if !o.status.success() => {
            ::zeroclaw_log::record!(
                WARN,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Note)
                    .with_outcome(::zeroclaw_log::EventOutcome::Unknown),
                &format!(
                    "Failed to take ownership of key file via takeown (exit code {:?})",
                    o.status.code()

View on GitHub (pinned to 88bb9c8533)

Solutions

Run the initial provisioning (`zeroclaw quickstart`) in a normal interactive user session where USERNAME is set, so the key file is created once; later service runs only read it
Set USERNAME explicitly in the service/scheduled-task environment to the account's actual user name
Ensure whoami.exe is reachable via PATH and not blocked by policy

Defensive patterns

Strategy: validation

Validate before calling

// run before provisioning on Windows:
#[cfg(windows)]
fn username_known() -> bool {
    std::env::var("USERNAME").map(|v| !v.trim().is_empty()).unwrap_or(false)
        || std::process::Command::new("whoami").output()
            .map(|o| o.status.success()).unwrap_or(false)
}

Try / catch

if let Err(e) = provision_key(&path) {
    let msg = e.to_string();
    if msg.contains("Cannot determine current username") {
        eprintln!("run `zeroclaw quickstart` from an interactive session (or set USERNAME) so ACL hardening can identify the user");
    }
    return Err(e);
}

Prevention

Do first-run provisioning interactively; let services only read the already-created key
For unattended Windows installs, set USERNAME explicitly in the service environment

When it happens

Trigger: First-run master key creation on Windows inside a service/scheduled-task session where USERNAME is not set and whoami is unavailable or fails; hardened or minimal Windows environments where whoami is blocked; CI runners with scrubbed environment.

Common situations: Running ZeroClaw as a Windows service under an account profile that lacks USERPROFILE/USERNAME; sandboxed CI on Windows agents; group-policy-restricted hosts where whoami.exe is disallowed.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/9b73c42b8918f652. Report an issue: GitHub.