charmbracelet/crush · info

clipboard is empty or holds an unsupported format

Error message

clipboard is empty or holds an unsupported format

What it means

clipboard.ErrEmpty is returned by clipboard.Read when the clipboard holds no data for the requested format. Unlike ErrUnsupported this is not a platform problem: the platform supports the clipboard but the content doesn't match what was asked for (e.g. asking for FormatImage when only text is present, or reading an empty clipboard).

Source

Thrown at internal/clipboard/clipboard.go:24

import "errors"

// Format identifies the kind of data to read from the clipboard.
type Format int

const (
	// FormatText is plain UTF-8 text.
	FormatText Format = iota
	// FormatImage is binary image data (PNG).
	FormatImage
)

var (
	// ErrUnsupported is returned when clipboard access is not available on
	// the current platform.
	ErrUnsupported = errors.New("clipboard operations are not supported on this platform")
	// ErrEmpty is returned when the clipboard holds no data for the
	// requested format.
	ErrEmpty = errors.New("clipboard is empty or holds an unsupported format")
)

// Init initializes the clipboard subsystem. On unsupported platforms it
// returns ErrUnsupported but is otherwise safe to call.
func Init() error {
	return initClipboard()
}

// WriteText writes plain text to the system clipboard. On unsupported
// platforms it is a no-op.
func WriteText(text string) {
	writeText(text)
}

// Read returns the clipboard contents for the given format. It returns
// ErrEmpty when no matching data is present and ErrUnsupported on platforms
// without clipboard support.
func Read(f Format) ([]byte, error) {

View on GitHub (pinned to 7944b8e522)

Solutions

1. Copy the intended content again immediately before reading, ensuring the format matches (PNG image for FormatImage, plain text for FormatText).
2. Handle ErrEmpty as an expected, non-fatal outcome: prompt the user that nothing usable was found.
3. If reading images, verify the source app actually places PNG data on the clipboard rather than a file path or other MIME type.

Example fix

// before
data, err := clipboard.Read(clipboard.FormatImage)
if err != nil {
    return fmt.Errorf("clipboard read failed: %w", err)
}
// after
data, err := clipboard.Read(clipboard.FormatImage)
switch {
case errors.Is(err, clipboard.ErrEmpty):
    return nil // nothing copied; expected case
case err != nil:
    return fmt.Errorf("clipboard read failed: %w", err)
}

// Nothing to pre-validate: clipboard content is external state.
// Optionally check after read:
if len(data) == 0 { /* treat as empty */ }

data, err := clipboard.Read(clipboard.FormatImage)
switch {
case errors.Is(err, clipboard.ErrEmpty):
    showHint("Nothing to paste — copy an image first")
case err != nil:
    return err
}

When it happens

Trigger: clipboard.Read(clipboard.FormatImage) when the clipboard contains text or nothing; clipboard.Read(clipboard.FormatText) on an empty clipboard; copying data in a format the reader doesn't map (e.g. non-PNG image data).

Common situations: User pressed paste-image but never actually copied an image; clipboard was cleared by another app between copy and read; copied image is in a format (JPEG, BMP) the reader treats as unsupported for FormatImage.

Related errors

• clipboard operations are not supported on this platform
• unsupported by the running server
• Crush crashed. If metrics are enabled, we were notified abou
• empty providers list from catwalk
• file lock is held by another process

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/e39bc59199d83ad9. Report an issue: GitHub.