libnyanpasu/clash-nyanpasu · error

staged file is not a regular file

Error message

staged file is not a regular file

What it means

read_staged_resource validates that the staged file blob is a plain regular file before reading it. The path exists but is not a regular file (it is a symlink/reparse point, directory, FIFO, or other non-regular node). The code bails instead of reading it, protecting against following malicious or corrupted links in the staging area.

Source

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

        };
        let link_metadata = match std::fs::symlink_metadata(&link_path) {
            Ok(metadata) => Some(metadata),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
            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)?,
            }));

View on GitHub (pinned to f7dbce2997)

Solutions

1. Remove the non-regular node at the staged file path and re-run materialization so the blob is rewritten as a regular file.
2. Ensure the staging root is on a local filesystem that does not turn files into reparse points (avoid network shares/overlay mounts for the staging dir).
3. Check nothing (sync tools, antivirus, junction creation) is converting files in the staging directory into symlinks.
4. If you moved or restored the staging area manually, restore a regular-file blob with the expected content.

let md = std::fs::symlink_metadata(staged_file_path)?;
if md.is_symlink() || !md.is_file() {
    std::fs::remove_file(staged_file_path)?; // clear invalid node before retry
}

fn is_regular_file_node(p: &Path) -> bool {
    std::fs::symlink_metadata(p).map(|m| !m.is_symlink() && m.is_file()).unwrap_or(false)
}

match result {
    Err(e) if e.to_string().contains("staged file is not a regular file") => {
        remove_stale_staging(root, op_id)?;
        retry()
    }
    other => other,
}

When it happens

Trigger: The staged file path (stage_file_path(root, operation_id)) exists but symlink_metadata shows it is a symlink/reparse point or not a regular file — e.g. someone replaced the staged blob with a symlink, or the staging dir sits on a filesystem (like some network/overlay mounts) that reports unusual file types.

Common situations: Staging directory tampering or accidental replacement; WSL/Windows reparse points; NFS/SMB/overlay filesystems misreporting file types; a build/tool swapped the file for a link.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• staged symlink specification is not a regular file
• runtime candidate directory is a symlink or reparse point: {
• materialization has multiple staged resources
• backup file is not a regular file
• backup symlink specification is not a regular file

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