herdrdev/herdr · warning

failed to allocate unique clipboard image staging path

Error message

failed to allocate unique clipboard image staging path

What it means

stage() tried to generate a unique temporary filename for a clipboard image by probing candidate paths, and every candidate already existed, so it gives up with ErrorKind::AlreadyExists. In practice collisions are near-impossible unless the staging directory is being flooded or the random source is deterministic.

Source

Thrown at src/server/clipboard_image.rs:46

        let path = dir.join(format!(
            "client-{client_id}-clipboard-{unique}-{attempt}.{extension}"
        ));
        let mut options = fs::OpenOptions::new();
        options.write(true).create_new(true);
        restrict_file_options(&mut options);
        let mut file = match options.open(&path) {
            Ok(file) => file,
            Err(err) if err.kind() == io::ErrorKind::AlreadyExists => continue,
            Err(err) => return Err(err),
        };
        file.write_all(data)?;
        return Ok(StagedClipboardImage {
            paste_text: path.to_string_lossy().into_owned(),
            path,
        });
    }

    Err(io::Error::new(
        io::ErrorKind::AlreadyExists,
        "failed to allocate unique clipboard image staging path",
    ))
}

pub(crate) fn remove_files(paths: Vec<PathBuf>) {
    for path in paths {
        let _ = fs::remove_file(path);
    }
}

fn sanitize_extension(extension: &str) -> &'static str {
    if extension.eq_ignore_ascii_case("png") {
        "png"
    } else if extension.eq_ignore_ascii_case("jpg") || extension.eq_ignore_ascii_case("jpeg") {
        "jpg"
    } else if extension.eq_ignore_ascii_case("gif") {
        "gif"

View on GitHub (pinned to f457cff4f2)

Solutions

1. Retry the stage call; a fresh filename will almost certainly succeed
2. Clear stale files from the clipboard image staging directory
3. Ensure nothing is pre-creating files with the same naming scheme
4. If reproducible, check the uniqueness source used for filename generation

Err(e) if e.kind() == io::ErrorKind::AlreadyExists => retry stage()

When it happens

Trigger: Repeated staging attempts where generated filenames collide with existing files in the staging dir, e.g. extremely high paste volume, a seeded/deterministic RNG, or a stale staging directory full of files with the same naming pattern.

Common situations: Bulk automated clipboard paste testing, staging dir shared across many concurrent processes, or tests reusing the same temp dir without cleanup.

Related errors

• failed to create unique scrollback temp file
• encoded clipboard image exceeds protocol limit

AI-assisted analysis of herdrdev/herdr@f457cff4f2 (2026-08-28). Data as JSON: /api/errors/93f1dda2e27eb889. Report an issue: GitHub.