nats-io/nats-server · error

error writing checksum: %w

Error message

error writing checksum: %w

What it means

Returned when the checksum cannot be written back onto the end of the compressed block. After closing the compression writer, the library appends the uncompressed trailing checksum bytes to the output buffer; a Write error means the block cannot be completed correctly. The cause is wrapped with %w.

Source

Thrown at server/filestore.go:14531

	}

	input := bytes.NewReader(buf[:bodyLen])
	checksum := buf[bodyLen:]

	// Compress the block content, but don't compress the checksum.
	// We will preserve it at the end of the block as-is.
	if n, err := io.CopyN(writer, input, bodyLen); err != nil {
		return nil, fmt.Errorf("error writing to compression writer: %w", err)
	} else if n != bodyLen {
		return nil, fmt.Errorf("short write on body (%d != %d)", n, bodyLen)
	}
	if err := writer.Close(); err != nil {
		return nil, fmt.Errorf("error closing compression writer: %w", err)
	}

	// Now add the checksum back onto the end of the block.
	if n, err := output.Write(checksum); err != nil {
		return nil, fmt.Errorf("error writing checksum: %w", err)
	} else if n != checksumSize {
		return nil, fmt.Errorf("short write on checksum (%d != %d)", n, checksumSize)
	}

	return output.Bytes(), nil
}

func (alg StoreCompression) Decompress(buf []byte) ([]byte, error) {
	if len(buf) < checksumSize {
		return nil, fmt.Errorf("compressed buffer is too short")
	}
	bodyLen := int64(len(buf) - checksumSize)
	input := bytes.NewReader(buf[:bodyLen])

	var reader io.ReadCloser
	switch alg {
	case NoCompression:
		return buf, nil

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check the wrapped error via errors.Is/As to identify the writer failure
2. Ensure the output destination has capacity (disk/memory) for bodyLen + checksumSize bytes
3. Retry the compression of the block
4. If output is custom, verify its Write implementation handles the small checksum append

if checksum == nil || len(checksum) != checksumSize { return errors.New("checksum must be full size before appending") }

func isChecksumWriteError(err error) bool { return err != nil && strings.Contains(err.Error(), "error writing checksum") }

block, err := alg.Compress(body)
if err != nil {
    if strings.Contains(err.Error(), "error writing checksum") {
        // output writer failed; retry with fresh buffer/storage
    }
    return err
}

When it happens

Trigger: output.Write(checksum) returns err != nil right after writer.Close() in the StoreCompression compress function, typically because the underlying output buffer's writer errored.

Common situations: Disk-full on file-backed output, a failed/short underlying byte slice writer, or a custom io.Writer implementation that errors under memory pressure.

Related errors

• Error creating msg block file: %v
• failed to load block from disk: %w
• failed to write to temporary file: %w
• short write to temporary file (%d != %d)
• failed to sync temporary file: %w

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/69d6bc861d572e1b. Report an issue: GitHub.