golang/go · error

lzw: input byte too large for the litWidth

Error message

lzw: input byte too large for the litWidth

What it means

In lzw.Writer.Write, when litWidth is less than 8 the writer pre-scans every input byte and rejects any byte larger than (1<<litWidth)-1, because the encoder's literal alphabet cannot represent such values. With litWidth == 8 the check is skipped (maxLit becomes 0xFF, all byte values valid). The error is sticky on w.err.

Source

Thrown at src/compress/lzw/writer.go:132

			w.table[i] = invalidEntry
		}
		return errOutOfCodes
	}
	return nil
}

// Write writes a compressed representation of p to w's underlying writer.
func (w *Writer) Write(p []byte) (n int, err error) {
	if w.err != nil {
		return 0, w.err
	}
	if len(p) == 0 {
		return 0, nil
	}
	if maxLit := uint8(1<<w.litWidth - 1); maxLit != 0xff {
		for _, x := range p {
			if x > maxLit {
				w.err = errors.New("lzw: input byte too large for the litWidth")
				return 0, w.err
			}
		}
	}
	n = len(p)
	code := w.savedCode
	if code == invalidCode {
		// This is the first write; send a clear code.
		// https://www.w3.org/Graphics/GIF/spec-gif89a.txt Appendix F
		// "Variable-Length-Code LZW Compression" says that "Encoders should
		// output a Clear code as the first code of each image data stream".
		//
		// LZW compression isn't only used by GIF, but it's cheap to follow
		// that directive unconditionally.
		clear := uint32(1) << w.litWidth
		if err := w.write(w, clear); err != nil {
			return 0, err
		}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Use litWidth=8 for general byte data so the full 0..255 alphabet is encodable.
2. For palette-indexed data, ensure every index is strictly less than (1<<litWidth) and shrink the palette or raise litWidth accordingly.
3. Validate input bytes before Write rather than letting the encoder fail partway through a large buffer.

Example fix

// before: litWidth=2 cannot encode full palette indices
w := lzw.NewWriter(dst, lzw.LSB, 2)
w.Write([]byte{0x00, 0x05, 0xff}) // "input byte too large"

// after: choose litWidth that covers the alphabet
w := lzw.NewWriter(dst, lzw.LSB, 8)
w.Write([]byte{0x00, 0x05, 0xff})

func maxByteForLitWidth(litWidth int) int {
    if litWidth >= 8 { return 0xff }
    return (1 << litWidth) - 1
}

func validateInput(w *lzw.Writer, litWidth int, p []byte) error {
    max := byte(maxByteForLitWidth(litWidth))
    if max == 0xff { return nil }
    for _, x := range p {
        if x > max { return fmt.Errorf("byte %d exceeds litWidth %d alphabet", x, litWidth) }
    }
    return nil
}

if _, err := w.Write(p); err != nil {
    if err.Error() == "lzw: input byte too large for the litWidth" {
        // Raise litWidth to 8 or shrink the palette.
    }
}

When it happens

Trigger: Constructing a Writer with litWidth in [2,7] and then Write-ing a byte whose value exceeds the literal ceiling. E.g., litWidth=2 allows only bytes 0..3; writing byte 0x80 fails immediately.

Common situations: GIF encoders that misconfigure litWidth (using 2 for a 256-color image), palette indexing bugs that emit out-of-range indices, or passing litWidth from user input without validation.

Related errors

• lzw: unknown order
• lzw: unknown order
• lzw: litWidth %d out of range
• lzw: litWidth %d out of range
• gzip.Write: Extra data is too large

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/f0c865100180ea45. Report an issue: GitHub.