What causes "l0 retention check interval must be greater than 0" in benbjohnson/litestream?

Set l0-retention-check-interval to a positive duration (e.g. "10m"), or remove the key to use the default.

l0 retention check interval must be greater than 0

Error message

l0 retention check interval must be greater than 0

What it means

Sentinel error ErrInvalidL0RetentionCheckInterval is returned by Config.Validate when l0-retention-check-interval is configured but <= 0. This interval controls how often litestream runs the L0 retention cleanup check, so it must be positive. Wrapped in ConfigValidationError with Field "l0-retention-check-interval".

Source

Thrown at cmd/litestream/main.go:58

// 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 {
		return fmt.Sprintf("%s: %v (got %v)", e.Field, e.Err, e.Value)
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set l0-retention-check-interval to a positive duration (e.g. "10m"), or remove the key to use the default.
If you want fewer cleanup passes, raise the interval rather than zeroing it.
Fix the template/source emitting the zero value.

Example fix

# before
l0-retention-check-interval: 0
# after
l0-retention-check-interval: 10m

Defensive patterns

Strategy: validation

Validate before calling

if cfg.L0RetentionCheckInterval != nil && *cfg.L0RetentionCheckInterval <= 0 {
    return errors.New("l0-retention-check-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.ErrInvalidL0RetentionCheckInterval) {
        return fmt.Errorf("check interval %v at %s invalid", ve.Value, ve.Field)
    }
    return err
}

Prevention

To check less often, increase the interval — never set it to 0.
Ensure templated variables for intervals always render valid positive durations.
Run cfg.Validate() as a startup preflight.

When it happens

Trigger: Setting l0-retention-check-interval: 0 or a negative duration in the top-level config; Validate fails before the process starts — covered by main_test.go expecting errors.Is(err, ErrInvalidL0RetentionCheckInterval).

Common situations: Setting 0 intending 'never check' (instead remove the key or use defaults); templated config where the variable is empty and coerces to zero; unit typo producing zero-length duration.

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/560166726291b01f. Report an issue: GitHub.