benbjohnson/litestream · error

no snapshots available

Error message

no snapshots available

What it means

ErrNoSnapshots is returned when a restore finds no snapshot (LTX level-0) files on the replica to restore from. It is treated as a soft condition by db.go and the library examples: a fresh empty database will be created instead of failing.

Source

Thrown at litestream.go:33

	_ "modernc.org/sqlite"
)

// Naming constants.
const (
	MetaDirSuffix = "-litestream"
)

// SQLite checkpoint modes.
const (
	CheckpointModePassive  = "PASSIVE"
	CheckpointModeFull     = "FULL"
	CheckpointModeRestart  = "RESTART"
	CheckpointModeTruncate = "TRUNCATE"
)

// Litestream errors.
var (
	ErrNoSnapshots      = errors.New("no snapshots available")
	ErrChecksumMismatch = errors.New("invalid replica, checksum mismatch")
	ErrLTXCorrupted     = errors.New("ltx file corrupted")
	ErrLTXMissing       = errors.New("ltx file missing")
	ErrDiskFull         = errors.New("disk full")
)

// LTXError provides detailed context for LTX file errors with recovery hints.
type LTXError struct {
	Op      string // Operation that failed (e.g., "open", "read", "validate")
	Path    string // File path
	Level   int    // LTX level (0 = L0, etc.)
	MinTXID uint64 // Minimum transaction ID
	MaxTXID uint64 // Maximum transaction ID
	Err     error  // Underlying error
	Hint    string // Recovery hint for users
}

func (e *LTXError) Error() string {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the replica URL/bucket/prefix points at the storage that actually contains backups
2. Run `litestream ltx -level 0` against the replica to inspect available snapshots
3. Trigger a fresh sync/snapshot first, then restore
4. If an empty database is acceptable, handle errors.Is(err, ErrNoSnapshots) and proceed with a new DB

Example fix

// before
if err := replica.Restore(ctx, opt); err != nil { return err }
// after
if err := replica.Restore(ctx, opt); err != nil {
    if errors.Is(err, litestream.ErrNoSnapshots) {
        log.Println("no backup found, creating fresh database")
        return nil
    }
    return err
}

// verify snapshots exist before restoring:
// litestream ltx -level 0 -replica <url>
// or in code, list replica contents and require >= 1 level-0 LTX file

if err := replica.Restore(ctx, opt); err != nil {
    if errors.Is(err, litestream.ErrNoSnapshots) || errors.Is(err, litestream.ErrTxNotAvailable) {
        log.Println("no backup found, creating new database")
        return nil
    }
    return err
}

When it happens

Trigger: Replica.Restore/db.Replica.Restore on a replica whose storage has never completed a snapshot, after retention deleted all snapshots, or pointing restore at the wrong bucket/path/replica URL.

Common situations: Restoring a brand-new database before the first sync produced a snapshot; misconfigured S3 bucket or prefix; retention/lifecycle rules purged objects; using `litestream ltx` cleanup then immediately restoring.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• no replica client configured
• restore from backup: %w
• remote position: %w
• list generations: %w
• list snapshots for generation %s: %w

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