benbjohnson/litestream · error

failed to list objects: %w

Error message

failed to list objects: %w

What it means

Wraps objectStore.List failure in the NATS replica client's LTXFiles. Fires when listing all objects in the NATS object store fails (connection or server error), so the LTX file iterator cannot be built; distinct from os.ErrNotExist handling.

Source

Thrown at nats/replica_client.go:298

}

// LTXFiles returns an iterator of all LTX files on the replica for a given level.
// NATS always uses accurate timestamps from headers since they're included in LIST operations at zero cost.
// The useMetadata parameter is ignored.
func (c *ReplicaClient) LTXFiles(ctx context.Context, level int, seek ltx.TXID, useMetadata bool) (ltx.FileIterator, error) {
	if err := c.Init(ctx); err != nil {
		return nil, err
	}

	// List all objects in the store
	internal.OperationTotalCounterVec.WithLabelValues(ReplicaClientType, "LIST").Inc()
	objectList, err := c.objectStore.List(ctx)
	if err != nil {
		// NATS returns "no objects found" when bucket is empty, treat as empty list
		if strings.Contains(err.Error(), "no objects found") {
			objectList = nil // Empty list
		} else {
			return nil, fmt.Errorf("failed to list objects: %w", err)
		}
	}

	prefix := litestream.LTXLevelDir(c.Path, level) + "/"
	fileInfos := make([]*ltx.FileInfo, 0, len(objectList))

	for _, objInfo := range objectList {
		// Filter by level prefix
		if !strings.HasPrefix(objInfo.Name, prefix) {
			continue
		}

		fileLevel, minTXID, maxTXID, err := c.parseLTXPath(objInfo.Name)
		if err != nil {
			continue // Skip invalid paths
		}

		if fileLevel != level {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the NATS bucket exists and credentials allow list access
2. Check NATS server connectivity and JetStream enablement
3. Retry; transient NATS errors are retried on the next sync

When it happens

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