What causes "Expected an absolute local path" in BigPizzaV3/CodexPlusPlus?

Make the configured path absolute (include drive letter, e.g. C:\\...) in config or arguments

Expected an absolute local path

Error message

Expected an absolute local path

What it means

plain_path in native_browser.rs enforces the path-safety contract for native browser roots and pinned paths: the path must be absolute. Relative paths cannot be safely canonicalized/pinned across processes, so this check runs first before the symlink/junction checks.

Solutions

Make the configured path absolute (include drive letter, e.g. C:\\...) in config or arguments
Canonicalize relative input before calling: std::fs::canonicalize or dunce::canonicalize on the base dir then join
Reject/repair empty or relative env-derived values at config load time
Join relative user input onto an absolute base dir before invoking the browser APIs

Example fix

// before
plain_path(Path::new("browser-data/runtime"))?;
// after
let abs = std::path::absolute(base_dir.join("browser-data/runtime"))?;
plain_path(&abs)?;

Defensive patterns

Strategy: validation

Validate before calling

fn ensure_absolute(p: &std::path::Path) -> bool {
    p.is_absolute()
}

Type guard

fn is_absolute_path(p: &Path) -> bool { p.is_absolute() }

Try / catch

match plain_path(p) {
    Err(e) if e.to_string().contains("absolute local path") => {
        let abs = std::path::absolute(p)?;
        plain_path(&abs)?;
    }
    other => other?,
}

Prevention

Store absolute paths in config; expand env vars at load time
Never build paths via raw string concatenation without a base dir
Validate path absoluteness at configuration ingest, not at use time

When it happens

Trigger: Any of plain_path's callers — pin_parents, selected_key, discover, prepare, restore_all, reconcile_contract — receiving a relative path from config, CLI input, or environment-derived values and passing it into plain_path.

Common situations: Config values like `runtime_root = "browser-data"` without a drive/absolute prefix; paths built via string concatenation without std::env::current_dir; variables that resolve to empty/relative values on the machine.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of BigPizzaV3/CodexPlusPlus@b1ed92e5e4 (2026-09-19). Data as JSON: /api/errors/e5714d81286f36de. Report an issue: GitHub.

Appendix: source

Thrown at crates/codex-plus-core/src/native_browser.rs:110

struct Journal {
    schema: u32,
    original_sha: String,
    candidate_sha: String,
    modified_secs: u64,
    modified_nanos: u32,
}

fn sha(bytes: &[u8]) -> String {
    format!("{:x}", Sha256::digest(bytes))
}

fn key_valid(key: &str) -> bool {
    key.len() == 16 && key.bytes().all(|b| b.is_ascii_hexdigit())
}

// Reject junctions as well as symlinks, including in parent directories.
fn plain_path(path: &Path) -> Result<()> {
    ensure!(path.is_absolute(), "Expected an absolute local path");
    for ancestor in path.ancestors() {
        if let Ok(meta) = fs::symlink_metadata(ancestor) {
            ensure!(
                !meta.file_type().is_symlink(),
                "Linked paths are unsupported"
            );
            #[cfg(windows)]
            {
                use std::os::windows::fs::MetadataExt;
                ensure!(
                    meta.file_attributes() & 0x400 == 0,
                    "Reparse paths are unsupported"
                );
            }
        }
    }
    ensure!(
        !path

View on GitHub (pinned to b1ed92e5e4)