warpdotdev/warp · error

could not determine home directory

Error message

could not determine home directory

What it means

Thrown by the parent-bridge state-root resolver when neither OZ_MESSAGE_LISTENER_STATE_ROOT_ENV nor the legacy LEGACY_MESSAGE_LISTENER_STATE_ROOT_ENV is set (or non-empty) and dirs::home_dir() returns None. Without a root there is nowhere to create the bridge's state/staged/surfaced directories.

Source

Thrown at app/src/ai/agent_sdk/driver/harness/claude_code/parent_bridge.rs:260

        }
        Ok(())
    }
}

pub(super) fn parent_bridge_root() -> Result<PathBuf> {
    for env_name in [
        OZ_MESSAGE_LISTENER_STATE_ROOT_ENV,
        LEGACY_MESSAGE_LISTENER_STATE_ROOT_ENV,
    ] {
        if let Ok(dir) = std::env::var(env_name)
            && !dir.is_empty()
        {
            return Ok(PathBuf::from(dir));
        }
    }
    dirs::home_dir()
        .map(|home| home.join(PARENT_BRIDGE_DEFAULT_STATE_ROOT))
        .ok_or_else(|| anyhow!("could not determine home directory"))
}

fn parent_bridge_staged_dir(state_dir: &Path) -> PathBuf {
    state_dir.join("staged")
}

fn parent_bridge_surfaced_dir(state_dir: &Path) -> PathBuf {
    state_dir.join(PARENT_BRIDGE_SURFACED_DIR_NAME)
}

pub(super) fn parent_bridge_hook_output_file(state_dir: &Path) -> PathBuf {
    state_dir.join(PARENT_BRIDGE_HOOK_OUTPUT_FILE_NAME)
}

pub(super) fn parent_bridge_hook_output_ack_file(state_dir: &Path) -> PathBuf {
    state_dir.join(PARENT_BRIDGE_HOOK_OUTPUT_ACK_FILE_NAME)
}

View on GitHub (pinned to e72fd7aacb)

Solutions

1. Set OZ_MESSAGE_LISTENER_STATE_ROOT_ENV to a writable directory; it takes precedence over home.
2. Otherwise set HOME (or USERPROFILE) to a writable path in the agent's environment.
3. Confirm with: printenv OZ_MESSAGE_LISTENER_STATE_ROOT HOME before launching.

Example fix

# before
warp agent run --harness claude …  # no state-root env, no HOME

# after
export OZ_MESSAGE_LISTENER_STATE_ROOT=/var/lib/warp/oz-message-listener
warp agent run --harness claude …

let state_root_ok = [OZ_MESSAGE_LISTENER_STATE_ROOT_ENV, LEGACY_MESSAGE_LISTENER_STATE_ROOT_ENV]
    .iter()
    .any(|k| std::env::var(k).map(|v| !v.is_empty()).unwrap_or(false))
    || dirs::home_dir().is_some();
anyhow::ensure!(state_root_ok, "set OZ_MESSAGE_LISTENER_STATE_ROOT or HOME");

fn bridge_state_root_resolvable() -> bool {
    dirs::home_dir().is_some()
        || std::env::var("OZ_MESSAGE_LISTENER_STATE_ROOT").map(|v| !v.is_empty()).unwrap_or(false)
}

match bridge_state_root() {
    Err(err) if err.to_string().contains("could not determine home directory") => {
        std::env::set_var("OZ_MESSAGE_LISTENER_STATE_ROOT", "/tmp/warp-bridge");
        bridge_state_root()
    }
    rest => rest,
}

When it happens

Trigger: Starting the Claude message bridge in an environment with both state-root env vars unset and no home directory resolvable — unset HOME/USERPROFILE, getpwuid failure, stripped container or service context.

Common situations: Running the Claude harness in Docker/systemd/CI where HOME was never set; the env vars that override state location not being propagated to the agent process; hardened images with synthetic users lacking passwd entries.

Related errors

• could not determine home directory
• could not determine home directory
• Could not determine home directory
• Agent driver dropped while starting Claude message bridge
• could not determine home directory

AI-assisted analysis of warpdotdev/warp@e72fd7aacb (2026-08-16). Data as JSON: /api/errors/ef954a1a07052613. Report an issue: GitHub.