What causes "sync interval must be greater than 0" in benbjohnson/litestream?

Set sync-interval to a positive duration (e.g. "1s"), or remove the key to use the default.

sync interval must be greater than 0

Error message

sync interval must be greater than 0

What it means

Sentinel error ErrInvalidSyncInterval is returned by Config.Validate when a replica sync-interval is configured but <= 0. Sync interval controls how often a replica polls the database WAL for new data, so a non-positive value is rejected. Wrapped in ConfigValidationError with fields like dbs[<id>].replica.sync-interval or dbs[<id>].replicas[<i>].sync-interval.

Source

Thrown at cmd/litestream/main.go:56

// Version is set via -ldflags "-X main.Version=..." on release and Makefile
// builds; otherwise it is resolved from embedded VCS build info at startup.
var Version = defaultVersion

func init() {
	bi, _ := debug.ReadBuildInfo()
	Version = resolveVersion(Version, bi)
}

// errStop is a terminal error for indicating program should quit.
var errStop = errors.New("stop")

// Sentinel errors for configuration validation
var (
	ErrInvalidSnapshotInterval         = errors.New("snapshot interval must be greater than 0")
	ErrInvalidSnapshotRetention        = errors.New("snapshot retention must be greater than 0")
	ErrInvalidCompactionInterval       = errors.New("compaction interval must be greater than 0")
	ErrInvalidSyncInterval             = errors.New("sync interval must be greater than 0")
	ErrInvalidL0Retention              = errors.New("l0 retention must not be negative")
	ErrInvalidL0RetentionCheckInterval = errors.New("l0 retention check interval must be greater than 0")
	ErrInvalidShutdownSyncTimeout      = errors.New("shutdown-sync-timeout must be >= 0")
	ErrInvalidShutdownSyncInterval     = errors.New("shutdown sync interval must be greater than 0")
	ErrInvalidHeartbeatURL             = errors.New("heartbeat URL must be a valid HTTP or HTTPS URL")
	ErrInvalidHeartbeatInterval        = errors.New("heartbeat interval must be at least 1 minute")
	ErrConfigFileNotFound              = errors.New("config file not found")
)

// ConfigValidationError wraps a validation error with additional context
type ConfigValidationError struct {
	Err   error
	Field string
	Value interface{}
}

func (e *ConfigValidationError) Error() string {
	if e.Value != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set sync-interval to a positive duration (e.g. "1s"), or remove the key to use the default.
Check both the singular replica block and each entry of the replicas[] list in the offending dbs entry.
Correct the source (template, env expansion) that produced the zero value.

Example fix

# before
dbs:
  - path: /data/app.db
    replica:
      sync-interval: 0
# after
dbs:
  - path: /data/app.db
    replica:
      sync-interval: 1s

Defensive patterns

Strategy: validation

Validate before calling

func validSyncInterval(d time.Duration) bool { return d > 0 }
if db.Replica != nil && db.Replica.SyncInterval != nil && *db.Replica.SyncInterval <= 0 {
    return errors.New("replica.sync-interval must be > 0")
}

Try / catch

if err := cfg.Validate(); err != nil {
    var ve *main.ConfigValidationError
    if errors.As(err, &ve) && errors.Is(ve.Err, main.ErrInvalidSyncInterval) {
        return fmt.Errorf("sync interval invalid at %s = %v", ve.Field, ve.Value)
    }
    return err
}

Prevention

Use a small positive value like 1s for near-real-time replication instead of 0.
Validate both single-replica and replicas[] list entries.
Omit sync-interval entirely to accept the default.

When it happens

Trigger: Setting sync-interval: 0 (or negative) under dbs[].replica, or under any entry of dbs[].replicas[]; running Validate on a config loaded with such values.

Common situations: Trying to make replication 'as fast as possible' with 0; templated configs where the interval variable is unset; copy-pasting a per-db replica block into a replicas[] list without fixing values.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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