What causes "shutdown-sync-timeout must be >= 0" in benbjohnson/litestream?

Set shutdown-sync-timeout to a non-negative duration (e.g. "30s"); use 0 to skip the shutdown sync wait.

shutdown-sync-timeout must be >= 0

Error message

shutdown-sync-timeout must be >= 0

What it means

Sentinel error ErrInvalidShutdownSyncTimeout is returned by Config.Validate when shutdown-sync-timeout is configured with a negative value. This timeout bounds how long litestream waits for a final sync during shutdown; zero is allowed (no wait), but negative values are rejected. Wrapped in ConfigValidationError with Field "shutdown-sync-timeout".

Source

Thrown at cmd/litestream/main.go:59

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

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set shutdown-sync-timeout to a non-negative duration (e.g. "30s"); use 0 to skip the shutdown sync wait.
Check for sign or arithmetic errors in the value source.
Remove the key entirely to use the default timeout.

Example fix

# before
shutdown-sync-timeout: -1m
# after
shutdown-sync-timeout: 30s

Defensive patterns

Strategy: validation

Validate before calling

if cfg.ShutdownSyncTimeout != nil && *cfg.ShutdownSyncTimeout < 0 {
    return errors.New("shutdown-sync-timeout 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.ErrInvalidShutdownSyncTimeout) {
        return fmt.Errorf("shutdown timeout %v is negative", ve.Value)
    }
    return err
}

Prevention

Use 0 to skip the shutdown sync wait; negative values are never valid.
Watch for sign errors when deriving timeouts from other durations.
Validate the config in CI and at startup.

When it happens

Trigger: Setting shutdown-sync-timeout to a negative duration in the top-level config and running Validate.

Common situations: Sign typo in the duration string; computed values going negative; misunderstanding that 0 (not a negative) disables the shutdown wait.

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.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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