What causes "Unexpected observation path" in BigPizzaV3/CodexPlusPlus?

Inspect the observation directory and remove/replace the non-regular-file entry with a normal file

Unexpected observation path

Error message

Unexpected observation path

What it means

During observation hashing, each path expected to be a regular file is opened and metadata-checked; if metadata shows the path is not a plain file (directory, socket, symlink target, device), this error is thrown. It protects the observation fingerprint from being computed over non-file entries whose metadata would be meaningless.

Solutions

Inspect the observation directory and remove/replace the non-regular-file entry with a normal file
Log which path failed (wrap the ensure! with the path in the message) to identify the offending entry
Filter non-regular entries during directory collection (skip !meta.is_file()) instead of erroring
Check whether another process (editor temp files, sync daemons) creates directories/symlinks in the watched path

Example fix

// before
ensure!(meta.is_file(), "Unexpected observation path");
// after
ensure!(meta.is_file(), "Unexpected observation path: {}", path.display());
// or skip non-files:
if !meta.is_file() { continue; }

Defensive patterns

Strategy: validation

Validate before calling

const stat = fs.lstatSync(p);
if (!stat.isFile()) throw new Error(`observation path is not a regular file: ${p}`);

Type guard

const isRegularFile = (p: string): boolean => { try { return fs.statSync(p).isFile(); } catch { return false; } };

Try / catch

match observe_and_hash() {
    Err(e) if e.to_string().contains("Unexpected observation path") => {
        eprintln!("non-file entry in observation set; rescan after cleanup");
        cleanup_and_retry()
    }
    Err(e) => return Err(e),
}

Prevention

Only write regular files into watched/observation directories
Exclude symlinks, directories and special files when collecting paths
Avoid letting sync daemons or editors create temp dirs inside watched paths

When it happens

Trigger: monitor_once / idle observation runs hash a collected file path; path.exists() is true but file.metadata().is_file() returns false — e.g. a directory or special file appeared where observation records expect a regular file.

Common situations: A directory was created inside the observation set (mkdir instead of file write); a FIFO/socket/device node was placed in the watched directory; a symlink to a directory survived earlier checks; OS-specific special files in the runtime dir.

Related errors

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

Appendix: source

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

    }
    for key in keys {
        let runtime = paths.runtime_root.join(key);
        files.insert(runtime.join(SERVICE));
        for (file, _) in RuntimeContract::pinned().files {
            files.insert(runtime.join(file));
        }
    }
    let mut hash = Sha256::new();
    for path in files {
        plain_path(&path)?;
        hash.update(path.to_string_lossy().as_bytes());
        if !path.exists() {
            hash.update(b"missing");
            continue;
        }
        let file = File::open(&path)?;
        let meta = file.metadata()?;
        ensure!(meta.is_file(), "Unexpected observation path");
        hash.update(format!(
            "{:?}:{:?}:{}",
            meta.created()?,
            meta.modified()?,
            meta.len()
        ));
        #[cfg(windows)]
        {
            use std::os::windows::io::AsRawHandle;
            use windows::Win32::Foundation::HANDLE;
            use windows::Win32::Storage::FileSystem::{
                BY_HANDLE_FILE_INFORMATION, GetFileInformationByHandle,
            };
            let mut identity = BY_HANDLE_FILE_INFORMATION::default();
            unsafe {
                GetFileInformationByHandle(HANDLE(file.as_raw_handle()), &mut identity)?;
            }
            ensure!(

View on GitHub (pinned to b1ed92e5e4)