{"record":{"id":"22a9a4cb21f3d9a8","repo":"k3s-io/k3s","slug":"etcd-s3-timeout-must-be-greater-than-0s","errorCode":null,"errorMessage":"etcd-s3-timeout must be greater than 0s","messagePattern":"etcd-s3-timeout must be greater than 0s","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/server/server.go","lineNumber":216,"sourceCode":"\tserverConfig.ControlConfig.EtcdExposeMetrics = cfg.EtcdExposeMetrics\n\tserverConfig.ControlConfig.EtcdDisableSnapshots = cfg.EtcdDisableSnapshots\n\tserverConfig.ControlConfig.SupervisorMetrics = cfg.SupervisorMetrics\n\tserverConfig.ControlConfig.VLevel = cmds.LogConfig.VLevel\n\tserverConfig.ControlConfig.VModule = cmds.LogConfig.VModule\n\n\tif !cfg.EtcdDisableSnapshots || cfg.ClusterReset {\n\t\tif cfg.EtcdSnapshotReconcile <= 0 {\n\t\t\treturn errors.New(\"etcd-snapshot-reconcile-interval must be greater than 0s\")\n\t\t}\n\t\tserverConfig.ControlConfig.EtcdSnapshotCompress = cfg.EtcdSnapshotCompress\n\t\tserverConfig.ControlConfig.EtcdSnapshotName = cfg.EtcdSnapshotName\n\t\tserverConfig.ControlConfig.EtcdSnapshotCron = cfg.EtcdSnapshotCron\n\t\tserverConfig.ControlConfig.EtcdSnapshotDir = cfg.EtcdSnapshotDir\n\t\tserverConfig.ControlConfig.EtcdSnapshotReconcile = metav1.Duration{Duration: cfg.EtcdSnapshotReconcile}\n\t\tserverConfig.ControlConfig.EtcdSnapshotRetention = cfg.EtcdSnapshotRetention\n\t\tif cfg.EtcdS3 {\n\t\t\tif cfg.EtcdS3Timeout <= 0 {\n\t\t\t\treturn errors.New(\"etcd-s3-timeout must be greater than 0s\")\n\t\t\t}\n\t\t\t// set default s3 retention from local snapshot retention\n\t\t\t// preserves legacy behavior of local snapshot retention also affecting s3\n\t\t\tif !app.IsSet(\"etcd-s3-retention\") && app.IsSet(\"etcd-snapshot-retention\") {\n\t\t\t\tcfg.EtcdS3Retention = cfg.EtcdSnapshotRetention\n\t\t\t}\n\t\t\tserverConfig.ControlConfig.EtcdS3 = &config.EtcdS3{\n\t\t\t\tAccessKey:     cfg.EtcdS3AccessKey,\n\t\t\t\tBucket:        cfg.EtcdS3BucketName,\n\t\t\t\tBucketLookup:  cfg.EtcdS3BucketLookupType,\n\t\t\t\tConfigSecret:  cfg.EtcdS3ConfigSecret,\n\t\t\t\tEndpoint:      cfg.EtcdS3Endpoint,\n\t\t\t\tEndpointCA:    cfg.EtcdS3EndpointCA,\n\t\t\t\tFolder:        cfg.EtcdS3Folder,\n\t\t\t\tInsecure:      cfg.EtcdS3Insecure,\n\t\t\t\tProxy:         cfg.EtcdS3Proxy,\n\t\t\t\tRegion:        cfg.EtcdS3Region,\n\t\t\t\tSecretKey:     cfg.EtcdS3SecretKey,","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/server/server.go#L198-L234","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set a positive duration, e.g. `--etcd-s3-timeout=30s` (or restore the 5m default by removing the flag)","If the goal was no S3 at all, remove --etcd-s3 / `etcd-s3: true` instead of zeroing the timeout","If disabling snapshots entirely, remove --cluster-reset from the same invocation as well","Audit /etc/rancher/k3s/config.yaml and K3S_* env vars for a zero/negative etcd-s3-timeout override"],"exampleFix":"# before\n# /etc/rancher/k3s/config.yaml\netcd-s3: true\netcd-s3-timeout: 0s\n\n# after\n# /etc/rancher/k3s/config.yaml\netcd-s3: true\netcd-s3-timeout: 5m","handlingStrategy":"validation","validationCode":"# preflight before starting k3s (config.yaml)\nif [ \"$(yq '.\"etcd-s3\" // false' /etc/rancher/k3s/config.yaml)\" = \"true\" ]; then\n  t=$(yq '.\"etcd-s3-timeout\" // \"5m\"' /etc/rancher/k3s/config.yaml)\n  case \"$t\" in 0s|0|0m|\"\"|-* ) echo \"etcd-s3-timeout must be positive\"; exit 1;; esac\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never zero a timeout flag to disable a feature; remove the feature flag instead","Lint config.yaml in CI with a policy that durations are strictly positive","Remember --cluster-reset re-activates the snapshot validation block even with --etcd-disable-snapshots"],"tags":["etcd","s3","backup","configuration","validation"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}