What causes "staged file hash mismatch" in libnyanpasu/clash-nyanpasu?

Re-run the materialization from scratch so the staged blob is rewritten and re-hashed.

staged file hash mismatch

Error message

staged file hash mismatch

What it means

After reading the staged file blob, read_staged_resource verifies its content against the expected tagged hash (hash_tagged(b"file", content)). The hash does not match, meaning the staged content changed since it was hashed (or the expected hash belongs to a different resource). This is an integrity check to detect truncated, edited, or mismatched staged data before promotion.

Source

Thrown at backend/tauri/src/service/profile_file.rs:784

            Err(error) => {
                return Err(error).with_context(|| {
                    format!(
                        "inspect staged symlink specification {}",
                        link_path.display()
                    )
                });
            }
        };
        if file_metadata.is_some() && link_metadata.is_some() {
            bail!("materialization has multiple staged resources");
        }
        if let Some(metadata) = file_metadata {
            if is_symlink_or_reparse(&metadata) || !metadata.is_file() {
                bail!("staged file is not a regular file");
            }
            let content = std::fs::read(&file_path)?;
            if hash_tagged(b"file", &content) != expected_hash {
                bail!("staged file hash mismatch");
            }
            return Ok(Some(StoredResource::File { path: file_path }));
        }
        if let Some(metadata) = link_metadata {
            if is_symlink_or_reparse(&metadata) || !metadata.is_file() {
                bail!("staged symlink specification is not a regular file");
            }
            let target = std::fs::read_to_string(&link_path)?;
            if hash_tagged(b"symlink", target.as_bytes()) != expected_hash {
                bail!("staged symlink hash mismatch");
            }
            return Ok(Some(StoredResource::Symlink {
                target: ExternalProfilePath::new(target)?,
            }));
        }
        Ok(None)
    }

View on GitHub (pinned to f7dbce2997)

Solutions

Re-run the materialization from scratch so the staged blob is rewritten and re-hashed.
Verify the expected_hash passed to read_staged_resource was computed from the same content that was staged in this operation.
Check for concurrent writers/readers of the staging directory and serialize access to one operation_id.
Check disk space and filesystem health; run fsck/chkdsk if corruption is suspected.

Defensive patterns

Strategy: retry

Try / catch

match result {
    Err(e) if e.to_string().contains("staged file hash mismatch") => {
        remove_stale_staging(root, op_id)?;
        retry_materialization() // restage content and recompute hash
    }
    other => other,
}

Prevention

Never reuse an expected_hash across different staged contents.
Ensure only one process stages/reads a given operation_id.
Verify adequate disk space; partial writes from ENOSPC cause mismatches.
Recompute the hash immediately after staging if you need to assert integrity yourself.

When it happens

Trigger: std::fs::read of stage_file_path succeeded but hash_tagged(b"file", &content) != expected_hash — the staged file was modified/truncated after staging, the write was not fully flushed (crash/power loss), or the expected_hash passed to read_staged_resource corresponds to a different resource/version than what was staged.

Common situations: Disk full or crash during write_private_file_new leaving a partial blob; reusing an old expected hash after re-generating profile content; concurrent edits to the staging directory; restoring an older staging snapshot from backup.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of libnyanpasu/clash-nyanpasu@f7dbce2997 (2026-09-08). Data as JSON: /api/errors/a65d7fd08296c1c9. Report an issue: GitHub.