Hmbown/CodeWhale · warning

Clipboard unavailable

Error message

Clipboard unavailable: {err}

What it means

write_text wraps any failure of the terminal-client-only clipboard path (enqueue_terminal_write) into a generic 'Clipboard unavailable' error. It means the terminal multiplexer/client clipboard transport could not accept the write — either the bounded queue was full or the writer was disconnected.

Solutions

1. Retry the copy after a short delay so the queued write can drain
2. Check the wrapped source error to distinguish 'still queued' (retry) from 'writer stopped' (reinit)
3. Switch the clipboard write order so a fallback transport (OSC52/wlcopy) is tried when the terminal-client path fails

Example fix

// before
clipboard.write_text(text).map_err(|e| anyhow!("Clipboard unavailable: {e}"))
// after
match clipboard.write_text(text) {
    Ok(()) => {},
    Err(e) if e.to_string().contains("still queued") => {
        std::thread::sleep(Duration::from_millis(50));
        clipboard.write_text(text)?;
    }
    Err(e) => return Err(e),
}

if clipboard.write_order() == ClipboardWriteOrder::TerminalClientOnly
    && clipboard.queue_is_saturated() {
    // defer the copy instead of calling write_text now
}

match clipboard.write_text(text) {
    Ok(()) => {},
    Err(e) if e.to_string().contains("still queued") => schedule_retry(text),
    Err(e) => try_osc52_fallback(text).unwrap_or_else(|e| log::warn!("{e}")),
}

When it happens

Trigger: Calling write_text while ClipboardWriteOrder::TerminalClientOnly is configured and enqueue_terminal_write fails: another write is still queued (bounded channel full) or the writer thread has stopped (disconnected).

Common situations: Spamming copy operations faster than the slow terminal transport drains them; running inside tmux/screen where client-only clipboard is required but the writer died; copy during shutdown.

Related errors

• another terminal clipboard write is still queued
• OSC 52 clipboard fallback requires a terminal
• selection is too large for OSC 52 clipboard fallback
• terminal clipboard writer stopped
• background hook supervisor queue is full

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/e7cf80c47c61b80b. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tui/clipboard.rs:590

    pub fn write_text(&mut self, text: &str) -> Result<()> {
        #[cfg(test)]
        {
            if let Some(writer) = self.terminal_writer.as_ref() {
                return writer.enqueue(text, self.terminal_context.in_tmux);
            }
            if self.fail_text_writes {
                bail!("test clipboard unavailable");
            }
            self.written_text.push(text.to_string());
            Ok(())
        }

        #[cfg(not(test))]
        {
            if self.terminal_context.write_order() == ClipboardWriteOrder::TerminalClientOnly {
                return self
                    .enqueue_terminal_write(text)
                    .map_err(|err| anyhow::anyhow!("Clipboard unavailable: {err}"));
            }

            #[cfg(all(target_os = "linux", not(target_env = "ohos")))]
            if write_text_with_wlcopy(text).is_ok() {
                return Ok(());
            }

            #[cfg(any(
                target_os = "macos",
                target_os = "windows",
                all(target_os = "linux", not(target_env = "ohos"))
            ))]
            {
                self.ensure_clipboard();
                if let Some(clipboard) = self.clipboard.as_mut()
                    && clipboard.set_text(text.to_string()).is_ok()
                {
                    return Ok(());

View on GitHub (pinned to 73e0f67d83)