benbjohnson/litestream · error

list v0.3.x snapshots for generation %s: %w

Error message

list v0.3.x snapshots for generation %s: %w

What it means

Wraps an error returned by the replica client's SnapshotsV3 call while enumerating v0.3.x-format snapshots for each generation during v0.3.x restore candidate selection. The wrapped underlying error (network, storage backend, or listing failure) is preserved via %w. It indicates Litestream could not determine which v0.3.x snapshots exist, so timestamp-based format selection cannot proceed.

Source

Thrown at replica.go:1383

	return nil
}

// findBestV3SnapshotForTimestamp returns the best v0.3.x snapshot for the given timestamp.
// Returns nil if no suitable snapshot exists.
func (r *Replica) findBestV3SnapshotForTimestamp(ctx context.Context, client ReplicaClientV3, timestamp time.Time) (*SnapshotInfoV3, error) {
	generations, err := client.GenerationsV3(ctx)
	if err != nil {
		return nil, fmt.Errorf("list v0.3.x generations: %w", err)
	}
	if len(generations) == 0 {
		return nil, nil
	}

	var allSnapshots []SnapshotInfoV3
	for _, gen := range generations {
		snapshots, err := client.SnapshotsV3(ctx, gen)
		if err != nil {
			return nil, fmt.Errorf("list v0.3.x snapshots for generation %s: %w", gen, err)
		}
		allSnapshots = append(allSnapshots, snapshots...)
	}

	if len(allSnapshots) == 0 {
		return nil, nil
	}

	// Sort by CreatedAt for timestamp-based selection.
	sortSnapshotsV3ByCreatedAt(allSnapshots)

	return findBestSnapshotV3(allSnapshots, timestamp), nil
}

// shouldUseV3Restore determines whether to use v0.3.x restore instead of LTX.
// Returns true if v0.3.x has a better backup for the given options.
func (r *Replica) shouldUseV3Restore(ctx context.Context, client ReplicaClientV3, timestamp time.Time) (bool, error) {
	// Get v0.3.x time bounds.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check the wrapped cause (%w) for the storage backend error and verify connectivity/credentials with the storage CLI (e.g. aws s3 ls).
2. Verify the generation directories exist at the replica path and were fully migrated from v0.3.x.
3. Re-run Restore; if only v0.3.x listing is broken, force LTX restore by restoring from a v0.5+ replica.
4. If the backend is permanently broken, re-replicate to a new generation before restoring.

Example fix

// before
snapshots, err := client.SnapshotsV3(ctx, gen)
if err != nil {
    return nil, fmt.Errorf("list v0.3.x snapshots for generation %s: %w", gen, err)
}
// after
// fix the cause: verify access before calling Restore
// $ aws s3 ls s3://bucket/db/generations/
// then retry:
snapshots, err := client.SnapshotsV3(ctx, gen)
if err != nil {
    return nil, fmt.Errorf("list v0.3.x snapshots for generation %s: %w", gen, err)
}

// Go: pre-flight listing check before restore
client, err := replica.NewReplicaClientFromURL(replicaURL)
if err != nil { return err }
gens, err := client.Generations(ctx)
if err != nil || len(gens) == 0 {
    return fmt.Errorf("replica generations not listable: %w", err)
}

if err := restore(...); err != nil {
    if strings.Contains(err.Error(), "list v0.3.x snapshots") {
        // inspect wrapped cause, verify storage credentials, retry with backoff
        return fmt.Errorf("v0.3.x listing failed, check backend access: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Restore (with a timestamp) on a replica whose storage backend fails the SnapshotsV3 listing: unreachable object store, deleted/missing generation directory, expired credentials, or a backend returning malformed listing results.

Common situations: S3/GCS/Azure credentials rotated or revoked; bucket renamed or region changed; v0.3.x replicas restored from a partial copy missing generation directories; network partition between Litestream and object storage.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• get v0.3.x time bounds: %w
• get LTX time bounds: %w
• find v0.3.x snapshot: %w
• find LTX snapshots: %w
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20

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