prepare does not support secretbox key type, use rotate-keys

Error message

prepare does not support secretbox key type, use rotate-keys instead

What it means

encryptionPrepare in pkg/server/handlers/secrets-encrypt.go implements the 'prepare' stage of the two-node-upgrade secrets-encryption flow. It explicitly rejects SecretBox clusters: secretbox keys cannot be staged through the annotation-driven prepare/rotate/reencrypt sequence, so it returns guidance to use the key-rotation path instead.

Source

Thrown at pkg/server/handlers/secrets-encrypt.go:247

		if err != nil {
			util.SendErrorWithID(err, "secret-encrypt", resp, req, http.StatusBadRequest)
			return
		}
		// If a user kills the k3s server immediately after this call, we run into issues where the files
		// have not yet been written. This sleep ensures that things have time to sync to disk before
		// the request completes.
		time.Sleep(1 * time.Second)
		resp.WriteHeader(http.StatusOK)
	})
}

func encryptionPrepare(ctx context.Context, control *config.Control, force bool) error {
	states := secretsencrypt.EncryptionStart + "-" + secretsencrypt.EncryptionReencryptFinished
	if err := verifyEncryptionHashAnnotation(control.Runtime, control.Runtime.Core.Core(), states); err != nil && !force {
		return err
	}
	if control.EncryptProvider == secretsencrypt.SecretBoxProvider {
		return errors.New("prepare does not support secretbox key type, use rotate-keys instead")
	}

	curKeys, err := secretsencrypt.GetEncryptionKeys(control.Runtime)
	if err != nil {
		return err
	}
	if err := AppendNewEncryptionKey(curKeys, control.EncryptProvider); err != nil {
		return err
	}

	if err := secretsencrypt.WriteEncryptionConfig(control.Runtime, curKeys, control.EncryptProvider, true); err != nil {
		return err
	}

	nodeName := os.Getenv("NODE_NAME")
	if err := secretsencrypt.WriteEncryptionHashAnnotation(ctx, control.Runtime, nodeName, false, secretsencrypt.EncryptionPrepare); err != nil {
		return err
	}

View on GitHub (pinned to 6ba341e396)

Solutions

Use the supported path for secretbox: 'k3s secrets-encrypt rotate-keys'.
If staged rotation is genuinely required, first plan a provider change to aes-cbc (re-encrypt), then prepare/rotate/reencrypt works.
Adjust automation to branch on 'k3s secrets-encrypt status' provider output.

Example fix

# before: rejected on secretbox clusters
k3s secrets-encrypt prepare

# after: supported key rotation
k3s secrets-encrypt rotate-keys

Defensive patterns

Strategy: fallback

Validate before calling

# Branch on the actual provider before staging
k3s secrets-encrypt status | grep -q secretbox && echo 'use rotate-keys, not prepare'

Try / catch

if err != nil && strings.Contains(err.Error(), "prepare does not support secretbox") {
    // fall back: k3s secrets-encrypt rotate-keys
}

Prevention

Remember secretbox is the k3s default; staged rotation is aes-cbc only.
Encode the provider check into runbooks so the wrong command is never attempted.

When it happens

Trigger: 'k3s secrets-encrypt prepare' (or PUT /v1-k3s/encrypt-config with stage prepare) on a server running with --secrets-encryption-provider=secretbox (the default provider).

Common situations: Following the staged-rotation runbook on a default-config cluster; automation written for AES-CBC clusters run against secretbox clusters.

Related errors

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