zeroclaw-labs/zeroclaw · error

JSONL archive changed during filesystem handoff

Error message

JSONL archive changed during filesystem handoff

What it means

Error "JSONL archive changed during filesystem handoff" thrown in zeroclaw-labs/zeroclaw.

Source

Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270

    fn archive_staged_jsonl(
        staged_path: &Path,
        migrated_path: &Path,
        expected: &(String, i64),
    ) -> Result<()> {
        std::fs::hard_link(staged_path, migrated_path).with_context(|| {
            format!(
                "Failed to create no-clobber JSONL archive {}",
                migrated_path.display()
            )
        })?;
        Self::sync_parent_directory(migrated_path)?;
        let archive_name = migrated_path
            .file_name()
            .and_then(|name| name.to_str())
            .unwrap_or("archive");
        if &Self::source_fingerprint(migrated_path, archive_name)? != expected {
            let _ = std::fs::remove_file(migrated_path);
            bail!("JSONL archive changed during filesystem handoff");
        }
        std::fs::remove_file(staged_path).with_context(|| {
            format!(
                "Failed to remove staged JSONL source {}",
                staged_path.display()
            )
        })?;
        Self::sync_parent_directory(staged_path)?;
        Ok(())
    }

    fn sync_parent_directory(path: &Path) -> Result<()> {
        #[cfg(unix)]
        {
            let parent = path
                .parent()
                .filter(|parent| !parent.as_os_str().is_empty())
                .unwrap_or_else(|| Path::new("."));

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Do not modify the JSONL session file while migration is running; stop writers and retry the handoff.

When it happens

Trigger: Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/883eccacf4db0e12. Report an issue: GitHub.