k3s-io/k3s · error

etcd-snapshot-reconcile-interval must be greater than 0s

Error message

etcd-snapshot-reconcile-interval must be greater than 0s

What it means

Server startup validates the etcd snapshot reconciler cadence whenever snapshots are active (i.e. --etcd-disable-snapshots is false) or a cluster-reset is in progress. The reconcile interval drives how often snapshots are taken/pruned; a zero or negative duration would stall that loop, so EtcdSnapshotReconcile <= 0 is rejected. Note the companion check: --etcd-s3 with --etcd-s3-timeout <= 0 fails similarly.

Source

Thrown at pkg/cli/server/server.go:206

	serverConfig.ControlConfig.DisableKubeProxy = cfg.DisableKubeProxy
	serverConfig.ControlConfig.DisableETCD = cfg.DisableETCD
	serverConfig.ControlConfig.DisableAPIServer = cfg.DisableAPIServer
	serverConfig.ControlConfig.DisableScheduler = cfg.DisableScheduler
	serverConfig.ControlConfig.DisableControllerManager = cfg.DisableControllerManager
	serverConfig.ControlConfig.DisableAgent = cfg.DisableAgent
	serverConfig.ControlConfig.EmbeddedRegistry = cfg.EmbeddedRegistry
	serverConfig.ControlConfig.ClusterInit = cfg.ClusterInit
	serverConfig.ControlConfig.EncryptSecrets = cfg.EncryptSecrets
	serverConfig.ControlConfig.EncryptProvider = cfg.EncryptProvider
	serverConfig.ControlConfig.EtcdExposeMetrics = cfg.EtcdExposeMetrics
	serverConfig.ControlConfig.EtcdDisableSnapshots = cfg.EtcdDisableSnapshots
	serverConfig.ControlConfig.SupervisorMetrics = cfg.SupervisorMetrics
	serverConfig.ControlConfig.VLevel = cmds.LogConfig.VLevel
	serverConfig.ControlConfig.VModule = cmds.LogConfig.VModule

	if !cfg.EtcdDisableSnapshots || cfg.ClusterReset {
		if cfg.EtcdSnapshotReconcile <= 0 {
			return errors.New("etcd-snapshot-reconcile-interval must be greater than 0s")
		}
		serverConfig.ControlConfig.EtcdSnapshotCompress = cfg.EtcdSnapshotCompress
		serverConfig.ControlConfig.EtcdSnapshotName = cfg.EtcdSnapshotName
		serverConfig.ControlConfig.EtcdSnapshotCron = cfg.EtcdSnapshotCron
		serverConfig.ControlConfig.EtcdSnapshotDir = cfg.EtcdSnapshotDir
		serverConfig.ControlConfig.EtcdSnapshotReconcile = metav1.Duration{Duration: cfg.EtcdSnapshotReconcile}
		serverConfig.ControlConfig.EtcdSnapshotRetention = cfg.EtcdSnapshotRetention
		if cfg.EtcdS3 {
			if cfg.EtcdS3Timeout <= 0 {
				return errors.New("etcd-s3-timeout must be greater than 0s")
			}
			// set default s3 retention from local snapshot retention
			// preserves legacy behavior of local snapshot retention also affecting s3
			if !app.IsSet("etcd-s3-retention") && app.IsSet("etcd-snapshot-retention") {
				cfg.EtcdS3Retention = cfg.EtcdSnapshotRetention
			}
			serverConfig.ControlConfig.EtcdS3 = &config.EtcdS3{
				AccessKey:     cfg.EtcdS3AccessKey,

View on GitHub (pinned to 6ba341e396)

Solutions

1. If snapshots should be off, use --etcd-disable-snapshots instead of a zero interval
2. Otherwise set a positive interval: --etcd-snapshot-reconcile-interval=5m (or your desired cadence)
3. Also keep --etcd-s3-timeout > 0 whenever --etcd-s3 is enabled
4. Review /etc/rancher/k3s/config.yaml for reconcile-interval: 0s leftovers after maintenance

Example fix

# before
k3s server --etcd-snapshot-reconcile-interval=0s  # -> must be greater than 0s

# after
either: k3s server --etcd-disable-snapshots
or:     k3s server --etcd-snapshot-reconcile-interval=5m

if !cfg.EtcdDisableSnapshots || cfg.ClusterReset {
    if cfg.EtcdSnapshotReconcile <= 0 {
        return errors.New("set --etcd-snapshot-reconcile-interval > 0s, or disable snapshots with --etcd-disable-snapshots")
    }
    if cfg.EtcdS3 && cfg.EtcdS3Timeout <= 0 {
        return errors.New("--etcd-s3 requires --etcd-s3-timeout > 0s")
    }
}

When it happens

Trigger: Setting --etcd-snapshot-reconcile-interval=0s (or a negative value) while leaving snapshots enabled; attempting to 'disable the reconciler' via the interval instead of --etcd-disable-snapshots; cluster-reset runs with a zeroed interval.

Common situations: Admins copying docs for disabling snapshots but zeroing the wrong flag; config.yaml merge setting reconcile-interval: 0s; tuning intervals down to 'off' during maintenance.

Related errors

• --server is required
• no snapshots given for removal
• invalid output format:
• Initial server URL host is not defined for load balancer
• etcd-s3-timeout must be greater than 0s

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/4a2938111de78159. Report an issue: GitHub.