benbjohnson/litestream · error

extract timestamp from LTX header: %w

Error message

extract timestamp from LTX header: %w

What it means

abs.WriteLTXFile failed to read the LTX header from the incoming stream via ltx.PeekHeader before uploading. It fires when the stream is shorter than an LTX header (ltx.HeaderSize) or contains a corrupt/invalid magic number, meaning the data being replicated is not a valid LTX file.

Source

Thrown at abs/replica_client.go:231

	return newLTXFileIterator(ctx, c, level, seek), nil
}

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

	key := litestream.LTXFilePath(c.Path, level, minTXID, maxTXID)

	// Use TeeReader to peek at LTX header while preserving data for upload
	var buf bytes.Buffer
	teeReader := io.TeeReader(rd, &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, rd))

	// Upload blob with proper content type, access tier, and metadata
	// Azure metadata keys cannot contain hyphens, so use litestreamtimestamp
	_, err = c.client.UploadStream(ctx, c.Bucket, key, rc, &azblob.UploadStreamOptions{
		HTTPHeaders: &blob.HTTPHeaders{
			BlobContentType: to.Ptr("application/octet-stream"),
		},
		AccessTier: to.Ptr(blob.AccessTierHot), // Use Hot tier as default
		Metadata: map[string]*string{
			MetadataKeyTimestamp: to.Ptr(timestamp.Format(time.RFC3339Nano)),
		},
	})
	if err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check upstream producer of the LTX stream for truncation or corruption
2. Verify the local shadow WAL/LTX files are not corrupted (litestream ltx to inspect)
3. If the local LTX state is corrupted, run 'litestream reset' to clear it and re-sync

When it happens

Trigger: Thrown at abs/replica_client.go:231 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/229f3d23299f2599. Report an issue: GitHub.