selection is too large for OSC 52 clipboard fallback

Error message

selection is too large for OSC 52 clipboard fallback

What it means

When not running inside tmux, `enqueue_terminal_write` writes the clipboard via an OSC 52 escape sequence emitted to stdout. OSC 52 payloads are base64-encoded and terminal emulators cap how much they accept, so selections larger than `OSC52_MAX_BYTES` are rejected up front with this error rather than being silently truncated or dropped by the terminal.

Solutions

Reduce the amount of text being copied to the clipboard
Run inside tmux, where the OSC 52 size gate is bypassed and tmux's own load-buffer path is used
Use a system clipboard helper (wl-copy/xclip/pbcopy) path instead of the terminal fallback

Example fix

// before
clipboard.write_text(&huge_output)?;
// after
if huge_output.len() > OSC52_MAX_BYTES {
    clipboard.write_text(&huge_output[..OSC52_MAX_BYTES])?; // or use a system helper
} else {
    clipboard.write_text(&huge_output)?;
}

Defensive patterns

Strategy: validation

Validate before calling

if !in_tmux && text.len() > OSC52_MAX_BYTES {
    // truncate, chunk, or route to a system clipboard helper instead
}

Type guard

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

Try / catch

match clipboard.write_text(text) {
    Err(e) if e.to_string().contains("too large for OSC 52") => {
        write_with_system_helper(text)?;
    }
    other => other?,
}

Prevention

Check `text.len()` against `OSC52_MAX_BYTES` before copying large selections
Prefer wl-copy/xclip/pbcopy for payloads beyond a few KiB
Warn users in the UI when a copy exceeds the OSC 52 limit

When it happens

Trigger: Calling `write_text` (which routes to `enqueue_terminal_write`) with a selection whose byte length exceeds `OSC52_MAX_BYTES`, while `terminal_context.in_tmux` is false.

Common situations: Yanking a very large block of text (logs, minified JSON, big code files) to the clipboard in a plain terminal without tmux; piping Codewhale output where stdout is large.

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@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/a938c142a7cafee6. Report an issue: GitHub.

Appendix: source

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

            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 73e0f67d83)