local workspace cwd must exist and be canonicalizable: {}: {

Error message

local workspace cwd must exist and be canonicalizable: {}: {e}

What it means

`validate_local_workspace_cwd` must canonicalize the requested workspace directory. If `canonicalize()` fails (path does not exist, is a broken symlink, or a permission error occurs), it wraps the io::Error with `local workspace cwd must exist and be canonicalizable: <path>: <e>` (session_startup.rs:503).

Source

Thrown at crates/codegen/xai-grok-pager/src/app/session_startup.rs:508

///
/// Returns the canonical directory so callers stamp and persist what was actually checked (symlinks and `..` must not diverge from validation).
#[cfg(feature = "local-workspace")]
pub fn validate_local_workspace_cwd(path: &std::path::Path) -> anyhow::Result<std::path::PathBuf> {
    let abs = if path.is_absolute() {
        path.to_path_buf()
    } else {
        std::env::current_dir()
            .unwrap_or_else(|_| std::path::PathBuf::from("."))
            .join(path)
    };
    let canon = abs.canonicalize().map_err(|e| {
        anyhow::anyhow!(
            "local workspace cwd must exist and be canonicalizable: {}: {e}",
            abs.display()
        )
    })?;
    if !canon.is_dir() {
        anyhow::bail!(
            "local workspace cwd must be an existing directory: {}",
            canon.display()
        );
    }
    if env_truthy(GROK_CHAT_LOCAL_WORKSPACE_ALLOW_HOME_ENV) {
        return Ok(canon);
    }
    if canon == std::path::Path::new("/") {
        anyhow::bail!("{LOCAL_WORKSPACE_HOME_DENIED}");
    }
    if let Some(home_path) = xai_dirs::home_dir() {
        let home_canon = home_path.canonicalize().unwrap_or(home_path);
        if canon == home_canon {
            anyhow::bail!("{LOCAL_WORKSPACE_HOME_DENIED}");
        }
    }
    Ok(canon)
}

View on GitHub (pinned to bc7f02eddd)

Solutions

Create the directory (`mkdir -p <path>`) or correct the path/typo
Fix or remove broken symlinks
Verify mount/permissions for the path (ls -ld)
Set GROK_CHAT_LOCAL_WORKSPACE_CWD to an existing absolute path

Example fix

// before
export GROK_CHAT_LOCAL_WORKSPACE_CWD=~/projects/missing-dir
// after
mkdir -p ~/projects/my-workspace
export GROK_CHAT_LOCAL_WORKSPACE_CWD=~/projects/my-workspace

Defensive patterns

Strategy: validation

Validate before calling

fn precheck_cwd(p: &std::path::Path) -> Result<(), String> {
    let canon = p.canonicalize().map_err(|e| format!("cwd unusable: {p:?}: {e}"))?;
    if !canon.is_dir() { return Err(format!("not a directory: {}", canon.display())); }
    Ok(())
}

Try / catch

match validate_local_workspace_cwd(&cwd) {
    Err(e) if e.to_string().contains("canonicalizable") => {
        eprintln!("create the directory or fix the path before retrying: {e}")
    }
    other => other?,
}

Prevention

mkdir -p the workspace before launching
Use absolute paths from `realpath` to avoid broken symlinks
Verify mounts (network drives, containers) exist before runs
Re-validate cwd if the shell has been alive across filesystem changes

When it happens

Trigger: Passing a `--local-workspace` cwd or GROK_CHAT_LOCAL_WORKSPACE_CWD pointing to a non-existent path; a dangling symlink; a path under a directory the user cannot traverse; cwd deleted after shell start.

Common situations: Typo'd directory names; workspaces on unmounted network drives; running inside a container where the host path does not exist.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/d46cb26537c5fe6b. Report an issue: GitHub.