hashicorp/nomad · error

could not add cipher: %w

Error message

could not add cipher: %w

What it means

After the DEK was decrypted, Encrypter.generateCipher failed while building the cipherSet from the root key, and the failure is wrapped as "could not add cipher". This error is retried with backoff before being returned from addCipher.

Source

Thrown at nomad/encrypter.go:617

		}
		return nil
	})
	if err != nil {
		return err
	}

	rootKey := &structs.UnwrappedRootKey{
		Meta:   meta,
		Key:    key,
		RSAKey: rsaKey,
	}

	var generatedCipher *cipherSet

	err = helper.WithBackoffFunc(ctx, minBackoff, maxBackoff, func() error {
		generatedCipher, err = e.generateCipher(rootKey)
		if err != nil {
			err := fmt.Errorf("could not add cipher: %w", err)
			e.log.Error(err.Error(), "key_id", meta.KeyID)
			return err
		}
		return nil
	})
	if err != nil {
		return err
	}

	// Send the cipher to the response channel or exit if the context is
	// canceled.
	//
	// The context is canceled when the server is shutting down or when another
	// task decrypting the same key completes.
	select {
	case <-ctx.Done():
		return ctx.Err()
	case respCh <- generatedCipher:

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Unwrap the inner error to see which generateCipher step failed and follow that specific fix
2. Validate the root key record in state (Meta, Algorithm, Key, RSAKey lengths) via keyring inspection endpoints
3. Rotate the affected key to regenerate a well-formed root key record
4. Upgrade/verify Nomad version consistency across agents if the key format changed between versions

// preflight: ensure the root key record is complete
if rootKey == nil || rootKey.Meta == nil || len(rootKey.Key) != 32 { /* reject before addCipher */ }

func validRootKey(k *structs.UnwrappedRootKey) bool { return k != nil && k.Meta != nil && k.Meta.KeyID != "" && len(k.Key) == 32 }

if err != nil {
    if strings.HasPrefix(err.Error(), "could not add cipher:") {
        // unwrap cause and fix key material, then retry rotation
    }
}

When it happens

Trigger: e.generateCipher(rootKey) returns an error — missing rootKey.Meta, unsupported algorithm, aead wrapper configuration failure, or RSA key parse failure (errors 2203-2206).

Common situations: A root key in state has corrupted or incomplete fields (nil Meta, zeroed Key, malformed RSAKey); upgrading from a version writing a different key format; a bug in state restoration producing partial UnwrappedRootKey values.

Related errors

• unable to decrypt wrapped key
• failed to configure keyring: %v
• failed to get active nomad key: %w
• rotated key does not exist in keyring: %w
• %w (root key): %w

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/3d965da49e595996. Report an issue: GitHub.