libnyanpasu/clash-nyanpasu · error

staged symlink specification is not a regular file

Error message

staged symlink specification is not a regular file

What it means

read_staged_resource found a staged symlink-spec file, but that spec file itself is not a regular file (it is a symlink/reparse point, directory, or other non-regular node). The symlink target string is stored in a plain spec file; if the spec file was replaced by a link or other node, the code refuses to read it to avoid following untrusted paths.

Source

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

                });
            }
        };
        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)
    }

    fn capture_backup(root: &Path, operation_id: &str, target: &Path) -> anyhow::Result<()> {
        match std::fs::symlink_metadata(target) {
            Ok(metadata) if metadata.file_type().is_symlink() => {
                let link_target = std::fs::read_link(target)?;
                let link_target = link_target
                    .to_str()

View on GitHub (pinned to f7dbce2997)

Solutions

  1. Delete the non-regular node at the staged link-spec path and re-run materialization to rewrite it as a regular file.
  2. Keep the staging root on a local, plain filesystem rather than network shares or containers' overlay volumes.
  3. Check that no background tool (sync/backup/AV) is rewriting files in the staging directory as symlinks.
Defensive patterns

Strategy: validation

Validate before calling

let md = std::fs::symlink_metadata(staged_link_path)?;
if md.is_symlink() || !md.is_file() {
    std::fs::remove_file(staged_link_path)?;
}

Type guard

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

Try / catch

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

Prevention

When it happens

Trigger: stage_link_path(root, operation_id) exists but symlink_metadata shows it is a symlink/reparse point or not a regular file — the spec file was replaced/tampered with, or the staging filesystem reports it as a special node.

Common situations: Manual manipulation of the staging dir; tools that convert spec files into links; unusual filesystems (reparse points on Windows, network mounts) hosting the staging root.

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

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