no user grok home resolved; refusing to write a cwd-relative

Error message

no user grok home resolved; refusing to write a cwd-relative pager.toml that startup would never read

What it means

persist_respect_manual_folds refuses to write pager.toml when xai_grok_config::user_grok_home() returns None, returning NotFound with this message. Writing a cwd-relative pager.toml would be silently ignored at startup, so the save is intentionally aborted. It protects the appearance/folds settings from being written where they can never be read.

Source

Thrown at crates/codegen/xai-grok-pager-render/src/appearance/config.rs:1895

        if !(trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with('[')) {
            out.push_str("# ");
        }
        out.push_str(line);
        out.push('\n');
    }
    out
}

/// Serializes the pager.toml read-modify-write so two rapid settings
/// toggles can't interleave and clobber each other (mirrors the shell's
/// `save_config` `SAVE_LOCK`).
static PAGER_TOML_SAVE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

pub fn persist_respect_manual_folds(enabled: bool) -> std::io::Result<()> {
    use std::io::{Error, ErrorKind};

    if xai_grok_config::user_grok_home().is_none() {
        return Err(Error::new(
            ErrorKind::NotFound,
            "no user grok home resolved; refusing to write a cwd-relative pager.toml \
             that startup would never read",
        ));
    }
    let _guard = PAGER_TOML_SAVE_LOCK
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());

    let path = crate::util::pager_toml_path();
    let content = match std::fs::read_to_string(&path) {
        Ok(c) => c,
        Err(e) if e.kind() == ErrorKind::NotFound => String::new(),
        Err(e) => return Err(e),
    };
    let updated = upsert_respect_manual_folds(&content, enabled)
        .map_err(|e| Error::new(ErrorKind::InvalidData, e))?;
    if let Some(dir) = path.parent() {

View on GitHub (pinned to bc7f02eddd)

Solutions

Set HOME (or the grok-home override env var) to an existing writable directory before invoking
Ensure the process runs as a user with a resolvable home directory
Persist settings in a context where the home is known, e.g. an interactive shell
Provide the setting via configuration/env rather than relying on the file save

Example fix

// before
persist_respect_manual_folds(true)?; // NotFound when HOME unset
// after
std::env::set_var("HOME", "/home/dev"); // or launch with a proper environment
persist_respect_manual_folds(true)?;

Defensive patterns

Strategy: validation

Validate before calling

if xai_grok_config::user_grok_home().is_none() {
    eprintln!("cannot persist pager.toml: no user grok home resolved");
    return;
}
persist_respect_manual_folds(enabled)?;

Try / catch

match persist_respect_manual_folds(enabled) {
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
        eprintln!("settings not saved: set HOME so pager.toml can be written");
    }
    other => other?,
}

Prevention

Verify user_grok_home() resolves before exposing settings-save UI
Launch services with HOME set to a writable directory
In tests, set a temp HOME/GROK home fixture
Never fall back to cwd-relative config writes

When it happens

Trigger: Calling persist_respect_manual_folds in an environment where no home directory resolves (HOME unset, no passwd entry, no valid GROK home override).

Common situations: Running under systemd services/cron with a scrubbed environment; containers without HOME set; test harnesses with cleared env vars.

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 xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/a0de9d227d336d9a. Report an issue: GitHub.