libnyanpasu/clash-nyanpasu · error

backup symlink specification is not a regular file

Error message

backup symlink specification is not a regular file

What it means

read_backup_resource reads the backed-up symlink specification (a plain file containing the original symlink target string). The spec file exists but is not a regular file (symlink/reparse point, directory, etc.), so the code refuses to read it for rollback to avoid following untrusted or corrupted nodes.

Source

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

            Ok(metadata) => Some(metadata),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
            Err(error) => {
                return Err(error)
                    .with_context(|| format!("inspect backup link {}", link_path.display()));
            }
        };
        if file_metadata.is_some() && link_metadata.is_some() {
            bail!("materialization has multiple backups");
        }
        if let Some(metadata) = file_metadata {
            if is_symlink_or_reparse(&metadata) || !metadata.is_file() {
                bail!("backup file is not a regular file");
            }
            return Ok(Some(StoredResource::File { path: file_path }));
        }
        if let Some(metadata) = link_metadata {
            if is_symlink_or_reparse(&metadata) || !metadata.is_file() {
                bail!("backup symlink specification is not a regular file");
            }
            let target = std::fs::read_to_string(&link_path)?;
            return Ok(Some(StoredResource::Symlink {
                target: ExternalProfilePath::new(target)?,
            }));
        }
        Ok(None)
    }

    fn create_ready_link(
        root: &Path,
        operation_id: &str,
        target: &ExternalProfilePath,
    ) -> anyhow::Result<PathBuf> {
        let ready = Self::ready_link_path(root, operation_id);
        match std::fs::symlink_metadata(&ready) {
            Ok(metadata) if metadata.file_type().is_symlink() => {
                if std::fs::read_link(&ready)? != target.as_path() {

View on GitHub (pinned to f7dbce2997)

Solutions

1. Delete the non-regular node at the backup link path and re-run the operation so the spec is rewritten as a regular file.
2. Move the backup root to a local plain filesystem away from junctions/placeholder-file services.
3. If the original managed symlink still exists and is valid, redo the materialization to recapture a clean backup.

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

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("backup symlink specification is not a regular file") => {
        clear_backup_dir(root, op_id)?;
        retry()
    }
    other => other,
}

When it happens

Trigger: backup_link_path(root, operation_id) exists but symlink_metadata reports a symlink/reparse point or a non-regular file — the spec was replaced by a link or the backup filesystem reports it as a special node.

Common situations: Backup dir tampering or wrong-file placement; storage on filesystems with reparse points (Windows junctions, OneDrive placeholder files, network mounts); restore tools that recreated backup files as links.

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

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

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