benbjohnson/litestream · error

failed to put object %s: %w

Error message

failed to put object %s: %w

What it means

objectStore.Put failed while uploading an LTX file to the NATS object store. Causes include connection loss, authorization failure, JetStream resource limits (stream max bytes), or a name conflict with an existing object.

Source

Thrown at nats/replica_client.go:419

	// 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
	internal.OperationTotalCounterVec.WithLabelValues(ReplicaClientType, "PUT").Inc()
	internal.OperationBytesCounterVec.WithLabelValues(ReplicaClientType, "PUT").Add(float64(objectInfo.Size))

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

// DeleteLTXFiles deletes one or more LTX files.
func (c *ReplicaClient) DeleteLTXFiles(ctx context.Context, a []*ltx.FileInfo) error {
	if err := c.Init(ctx); err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check NATS server connectivity and credentials
2. Verify JetStream stream limits (max bytes/max objects) are not exhausted
3. Retry the sync; uploads are retried on subsequent cycles

When it happens

Trigger: Thrown at nats/replica_client.go:419 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/64d9e3092b060f63. Report an issue: GitHub.