kovidgoyal/kitty · error

Received OSC %s packet from terminal with invalid base64 enc

Error message

Received OSC %s packet from terminal with invalid base64 encoded payload

What it means

Clipboard responses arrive as OSC packets whose payload is base64-encoded. parse_escape_code decodes parts[2] with StdEncoding; on decoding failure it reports an invalid base64 payload, meaning the OSC packet from the terminal was corrupted or malformed.

Source

Thrown at kittens/clipboard/read.go:257

	case "EPERM":
		return fmt.Errorf("permission denied")
	case "EBUSY":
		return fmt.Errorf("a temporary error occurred, try again later.")
	default:
		return fmt.Errorf("%s", status)
	}
}

func parse_escape_code(etype loop.EscapeCodeType, data []byte) (metadata map[string]string, payload []byte, err error) {
	if etype != loop.OSC || !bytes.HasPrefix(data, utils.UnsafeStringToBytes(OSC_NUMBER+";")) {
		return
	}
	parts := bytes.SplitN(data, utils.UnsafeStringToBytes(";"), 3)
	metadata = make(map[string]string)
	if len(parts) > 2 && len(parts[2]) > 0 {
		payload, err = base64.StdEncoding.DecodeString(utils.UnsafeBytesToString(parts[2]))
		if err != nil {
			err = fmt.Errorf("Received OSC %s packet from terminal with invalid base64 encoded payload", OSC_NUMBER)
			return
		}
	}
	if len(parts) > 1 {
		for record := range bytes.SplitSeq(parts[1], utils.UnsafeStringToBytes(":")) {
			rp := bytes.SplitN(record, utils.UnsafeStringToBytes("="), 2)
			v := ""
			if len(rp) == 2 {
				v = string(rp[1])
			}
			k := string(rp[0])
			metadata[k] = unescape_metadata_value(k, v)
		}
	}

	return
}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Enable tmux passthrough properly (set allow-passthrough on) or bypass tmux for the test
2. Update kitty (and the remote kitten) — sequence splitting bugs were fixed over time
3. For very large payloads, transfer via file (getfile) instead of inline payloads
4. Reproduce without intermediaries (direct kitty window) to isolate which layer corrupts the sequence

out=$(kitten clipboard get f 2>&1) || { echo "$out" | grep -q 'base64' && { sleep 1; kitten clipboard get f; }; }

When it happens

Trigger: An OSC 52-style clipboard response whose third ';' separated segment is not valid standard base64 — truncated by terminal line-length limits, mangled by tmux passthrough, or containing URL-safe/whitespace variants StdEncoding rejects.

Common situations: tmux or screen wrapping/reflowing long escape sequences; terminal buffer or pty limits truncating giant clipboard payloads; ssh sessions without proper escape passthrough; bugs in terminal emitters that split OSC sequences incorrectly.

Related errors

• Invalid base64 encoded data from terminal with error: %w
• Received incomplete data for clipboard
• Malformed OSC 5522: could not decode a metadata value. Error
• Malformed OSC 5522: read request payload is not valid base64
• Clipboard alias request payload is not valid base64 encoded

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/02c5f6c81f221e2d. Report an issue: GitHub.