benbjohnson/litestream · error

timestamp does not exist

Error message

timestamp does not exist

What it means

When RestoreOptions.Timestamp is set and time bounds exist, CalcRestoreTarget validates that the requested timestamp falls within [createdAt, updatedAt] of the available backups. If the timestamp is earlier than the oldest backup or later than the newest, this error is returned. It means litestream cannot guarantee a consistent restore at that point in time.

Source

Thrown at replica.go:590

		if err != nil {
			return time.Time{}, fmt.Errorf("v0.3.x time bounds: %w", err)
		}
		// Extend time bounds to include v0.3.x backups.
		if !v3CreatedAt.IsZero() && (createdAt.IsZero() || v3CreatedAt.Before(createdAt)) {
			createdAt = v3CreatedAt
		}
		if !v3UpdatedAt.IsZero() && (updatedAt.IsZero() || v3UpdatedAt.After(updatedAt)) {
			updatedAt = v3UpdatedAt
		}
	}

	// Skip if it does not contain timestamp.
	if !opt.Timestamp.IsZero() {
		if createdAt.IsZero() && updatedAt.IsZero() {
			return time.Time{}, fmt.Errorf("no backups found")
		}
		if opt.Timestamp.Before(createdAt) || opt.Timestamp.After(updatedAt) {
			return time.Time{}, fmt.Errorf("timestamp does not exist")
		}
	}

	return updatedAt, nil
}

// Replica restores the database from a replica based on the options given.
// This method will restore into opt.OutputPath, if specified, or into the
// DB's original database path. It can optionally restore from a specific
// replica or it will automatically choose the best one. Finally,
// a timestamp can be specified to restore the database to a specific
// point-in-time.
//
// When the replica contains both v0.3.x and LTX format backups, this method
// compares snapshots from both formats and uses whichever has the better backup:
// - With timestamp: uses the format with the most recent snapshot before timestamp
// - Without timestamp: uses the format with the most recent backup overall
func (r *Replica) Restore(ctx context.Context, opt RestoreOptions) (err error) {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Run `litestream ltx` (or query the restore target) to see the available time range and pick a timestamp inside it.
2. Check for clock skew/timezone issues and specify the timestamp in UTC.
3. If you need an earlier point than the oldest backup, restore to the oldest available timestamp or use another replica/snapshot.
4. Ensure replication is current if you intended a recent timestamp — trigger a sync and retry.

target, err := replica.CalcRestoreTarget(ctx, litestream.RestoreOptions{Timestamp: ts})
if err != nil {
    return fmt.Errorf("timestamp %s not restorable: %w", ts, err)
}
// target (updatedAt) is a valid restore point — use it

err := replica.Restore(ctx, opt)
if err != nil && strings.Contains(err.Error(), "timestamp does not exist") {
    // clamp requested time to [createdAt, updatedAt] and retry
}

When it happens

Trigger: Calling restore with a -timestamp outside the replicated range: e.g. a time before the first LTX file was ever uploaded, or a future/clock-skewed time after the latest backup.

Common situations: Restoring to a time from before the replica existed; host clock skew producing future timestamps; timezone confusion (passing local time where UTC is expected); asking for a moment after replication stopped.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• output path required
• cannot specify index & timestamp to restore
• snapshot interval must be greater than 0
• snapshot retention must be greater than 0

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