benbjohnson/litestream · error

abs: cannot upload ltx file %q: %w

Error message

abs: cannot upload ltx file %q: %w

What it means

The Azure blob UploadStream call failed while writing an LTX file to the container. This is a transient or permission I/O error against Azure Blob Storage: network failure, invalid bucket/container name, missing write authorization (RBAC or SAS), or wrong endpoint.

Source

Thrown at abs/replica_client.go:250

	}
	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 {
		return nil, fmt.Errorf("abs: cannot upload ltx file %q: %w", key, err)
	}

	internal.OperationTotalCounterVec.WithLabelValues(ReplicaClientType, "PUT").Inc()
	internal.OperationBytesCounterVec.WithLabelValues(ReplicaClientType, "PUT").Add(float64(rc.N()))

	return &ltx.FileInfo{
		Level:     level,
		MinTXID:   minTXID,
		MaxTXID:   maxTXID,
		Size:      rc.N(),
		CreatedAt: timestamp,
	}, nil
}

// OpenLTXFile returns a reader for an LTX file.
// Returns os.ErrNotExist if no matching min/max TXID is not found.
func (c *ReplicaClient) OpenLTXFile(ctx context.Context, level int, minTXID, maxTXID ltx.TXID, offset, size int64) (io.ReadCloser, error) {
	if err := c.Init(ctx); err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the container name exists and the credential has Storage Blob Data Contributor access
2. Check network connectivity and endpoint correctness
3. Retry the sync; Litestream will re-attempt the upload on the next cycle
4. Inspect the wrapped error for an azblob HttpResponse error code (AuthenticationFailed, ContainerNotFound, etc.)

When it happens

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