k3s-io/k3s · error

etcd-s3-timeout must be greater than 0s

Error message

etcd-s3-timeout must be greater than 0s

What it means

k3s validates etcd snapshot S3 settings at server startup. When snapshots are active (default) or --cluster-reset is set and --etcd-s3 is enabled, EtcdS3Timeout must be a positive duration because it bounds every S3 upload/download/read operation for snapshots. The flag defaults to 5m, so hitting this error means the operator explicitly set it to 0s or a negative value.

Source

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

	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,
				Bucket:        cfg.EtcdS3BucketName,
				BucketLookup:  cfg.EtcdS3BucketLookupType,
				ConfigSecret:  cfg.EtcdS3ConfigSecret,
				Endpoint:      cfg.EtcdS3Endpoint,
				EndpointCA:    cfg.EtcdS3EndpointCA,
				Folder:        cfg.EtcdS3Folder,
				Insecure:      cfg.EtcdS3Insecure,
				Proxy:         cfg.EtcdS3Proxy,
				Region:        cfg.EtcdS3Region,
				SecretKey:     cfg.EtcdS3SecretKey,

View on GitHub (pinned to 6ba341e396)

Solutions

1. Set a positive duration, e.g. `--etcd-s3-timeout=30s` (or restore the 5m default by removing the flag)
2. If the goal was no S3 at all, remove --etcd-s3 / `etcd-s3: true` instead of zeroing the timeout
3. If disabling snapshots entirely, remove --cluster-reset from the same invocation as well
4. Audit /etc/rancher/k3s/config.yaml and K3S_* env vars for a zero/negative etcd-s3-timeout override

Example fix

# before
# /etc/rancher/k3s/config.yaml
etcd-s3: true
etcd-s3-timeout: 0s

# after
# /etc/rancher/k3s/config.yaml
etcd-s3: true
etcd-s3-timeout: 5m

# preflight before starting k3s (config.yaml)
if [ "$(yq '."etcd-s3" // false' /etc/rancher/k3s/config.yaml)" = "true" ]; then
  t=$(yq '."etcd-s3-timeout" // "5m"' /etc/rancher/k3s/config.yaml)
  case "$t" in 0s|0|0m|""|-* ) echo "etcd-s3-timeout must be positive"; exit 1;; esac
fi

When it happens

Trigger: Running `k3s server --etcd-s3 --etcd-s3-timeout=0s` (or a negative duration), or config.yaml containing `etcd-s3: true` together with `etcd-s3-timeout: 0s`. Also fires when `etcd-disable-snapshots: true` is combined with `cluster-reset: true`, since the validation block still executes when ClusterReset is set.

Common situations: Config templates that zero out timeouts intending to disable a feature; YAML parsing `etcd-s3-timeout: 0` as integer 0; disabling snapshots with --etcd-disable-snapshots while forgetting that --cluster-reset re-enables the snapshot validation path.

Understand the failure class

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

Related errors

• s3 configuration was not set
• no snapshots given for removal
• invalid flag use; --cluster-reset required with --cluster-re
• s3 bucket name was not set
• invalid output format:

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