selection is too large for OSC 52 clipboard fallback

Error message

selection is too large for OSC 52 clipboard fallback

What it means

The OSC 52 clipboard fallback refuses to emit sequences larger than OSC52_MAX_BYTES (100 KiB) when not running under tmux. OSC 52 encodes the selection as base64 inside a terminal escape sequence, and many terminals truncate or drop oversized sequences, so the copy would silently fail. Under tmux the check is skipped because the write goes through tmux load-buffer instead.

Source

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

            if write_text_with_pbcopy(text).is_ok() {
                return Ok(());
            }

            #[cfg(target_os = "windows")]
            if write_text_with_set_clipboard(text).is_ok() {
                return Ok(());
            }

            self.enqueue_terminal_write(text)
                .map_err(|err| anyhow::anyhow!("Clipboard unavailable: {err}"))
        }
    }

    #[cfg(not(test))]
    fn enqueue_terminal_write(&mut self, text: &str) -> Result<()> {
        if !self.terminal_context.in_tmux {
            if text.len() > OSC52_MAX_BYTES {
                bail!("selection is too large for OSC 52 clipboard fallback");
            }
            if !io::stdout().is_terminal() {
                bail!("OSC 52 clipboard fallback requires a terminal");
            }
        }

        if self.terminal_writer.is_none() {
            self.terminal_writer = Some(TerminalClipboardWriter::spawn()?);
        }
        self.terminal_writer
            .as_ref()
            .expect("terminal clipboard writer initialized")
            .enqueue(text, self.terminal_context.in_tmux)
    }

    /// Return one completed background terminal clipboard write, if available.
    ///
    /// Successes are intentionally quiet because callers already show their

View on GitHub (pinned to 0c42157ee5)

Solutions

Install a native clipboard utility (wl-clipboard on Wayland, xclip/xsel on X11, pbcopy on macOS) so OSC 52 is not the fallback.
Copy a smaller selection; narrow the region to what you actually need (<100 KiB, roughly a few thousand lines).
Run the TUI inside tmux so the copy routes through tmux load-buffer, which is not subject to this cap.

Defensive patterns

Strategy: validation

Validate before calling

const OSC52_MAX_BYTES: usize = 100 * 1024;

fn selection_copyable_via_osc52(text: &str, in_tmux: bool) -> bool {
    in_tmux || text.len() <= OSC52_MAX_BYTES
}

Prevention

Install a native clipboard utility (pbcopy, wl-copy, xclip) so OSC 52 stays a last resort.
Cap copy-to-clipboard selections in your UI and warn above ~100 KiB outside tmux.
Run inside tmux when you routinely copy very large regions; load-buffer has no such cap.

When it happens

Trigger: Copying a selection larger than 100 KiB (about 25 KiB of text after base64 inflation, i.e. large multi-thousand-line selections) when no system clipboard utility (pbcopy/wl-copy/xclip) is available and the session is not inside tmux.

Common situations: Headless-ish setups with no clipboard helper installed; selecting whole files or huge command output in the TUI; minimal Linux containers or SSH sessions without X11/Wayland.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/a938c142a7cafee6. Report an issue: GitHub.