benbjohnson/litestream · error

invalid -timestamp, must specify in ISO 8601 format (e.g. 20

Error message

invalid -timestamp, must specify in ISO 8601 format (e.g. 2000-01-01T00:00:00Z)

What it means

This error is raised by the restore command's Run when the -timestamp flag cannot be parsed with time.Parse(time.RFC3339, ...). The restore point must be an ISO 8601 / RFC 3339 timestamp so it can be matched against replica positions.

Source

Thrown at cmd/litestream/restore.go:90

		ctx = cancelCtx
		defer cancel()
	}

	switch *integrityCheck {
	case "none":
		opt.IntegrityCheck = litestream.IntegrityCheckNone
	case "quick":
		opt.IntegrityCheck = litestream.IntegrityCheckQuick
	case "full":
		opt.IntegrityCheck = litestream.IntegrityCheckFull
	default:
		return fmt.Errorf("invalid -integrity-check value: %s", *integrityCheck)
	}

	// Parse timestamp, if specified.
	if *timestampStr != "" {
		if opt.Timestamp, err = time.Parse(time.RFC3339, *timestampStr); err != nil {
			return errors.New("invalid -timestamp, must specify in ISO 8601 format (e.g. 2000-01-01T00:00:00Z)")
		}
	}

	// Determine replica to restore from.
	var r *litestream.Replica
	if litestream.IsURL(fs.Arg(0)) {
		if *configPath != "" {
			return fmt.Errorf("cannot specify a replica URL and the -config flag")
		}
		if r, err = c.loadFromURL(ctx, fs.Arg(0), *ifDBNotExists, &opt); errors.Is(err, errSkipDBExists) {
			slog.Info("database already exists, skipping")
			return nil
		} else if err != nil {
			return err
		}
	} else {
		if *configPath == "" {
			*configPath = DefaultConfigPath()

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Format the value as RFC3339, e.g. 2024-01-01T10:00:00Z
2. Include a UTC offset (Z or +02:00) — it is mandatory
3. Drop the -timestamp flag to restore to the latest available state

Example fix

// before
litestream restore -timestamp 2024-01-01 10:00:00 -o db.sqlite repl
// after
litestream restore -timestamp 2024-01-01T10:00:00Z -o db.sqlite repl

ts, err := time.Parse(time.RFC3339, *timestamp)
if err != nil {
    return fmt.Errorf("-timestamp must be RFC3339 like 2006-01-02T15:04:05Z")
}

When it happens

Trigger: Passing -timestamp with a non-RFC3339 value: "2024-01-01" (date only), "2024-01-01 10:00:00" (space instead of T), missing timezone, or Unix epoch numbers.

Common situations: Users copying timestamps from logs or database dumps in local formats, or passing a relative value like "1 hour ago" expecting natural-language parsing.

Related errors

• timestamp does not exist
• database path required
• database path required
• delete percentage must be between 0 and 100
• source database path required

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