benbjohnson/litestream · error

extract timestamp from LTX header: %w

Error message

extract timestamp from LTX header: %w

What it means

nats.WriteLTXFile failed to peek the LTX header from the incoming stream (ltx.PeekHeader). The stream is shorter than an LTX header or has invalid magic, so the data being written to NATS is not a valid LTX file.

Source

Thrown at nats/replica_client.go:404

	return objectResult, nil
}

// WriteLTXFile writes an LTX file to the replica.
func (c *ReplicaClient) WriteLTXFile(ctx context.Context, level int, minTXID, maxTXID ltx.TXID, r io.Reader) (*ltx.FileInfo, error) {
	if err := c.Init(ctx); err != nil {
		return nil, err
	}

	objectPath := c.ltxPath(level, minTXID, maxTXID)

	// Use TeeReader to peek at LTX header while preserving data for upload
	var buf bytes.Buffer
	teeReader := io.TeeReader(r, &buf)

	// Extract timestamp from LTX header
	hdr, _, err := ltx.PeekHeader(teeReader)
	if err != nil {
		return nil, fmt.Errorf("extract timestamp from LTX header: %w", err)
	}
	timestamp := time.UnixMilli(hdr.Timestamp).UTC()

	// Combine buffered data with rest of reader
	rc := internal.NewReadCounter(io.MultiReader(&buf, r))

	// Store timestamp in NATS object headers for accurate timestamp retrieval
	objectInfo, err := c.objectStore.Put(ctx, jetstream.ObjectMeta{
		Name: objectPath,
		Headers: map[string][]string{
			HeaderKeyTimestamp: {timestamp.Format(time.RFC3339Nano)},
		},
	}, rc)
	if err != nil {
		return nil, fmt.Errorf("failed to put object %s: %w", objectPath, err)
	}

	// Record metrics

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check the producer of the LTX stream for truncation/corruption
2. Inspect local LTX files with 'litestream ltx'; reset local state if corrupted

When it happens

Trigger: Thrown at nats/replica_client.go:404 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/aa43d92023ac8473. Report an issue: GitHub.