What causes "root key algorithm is required" in hashicorp/nomad?

Set Algorithm to a supported value such as structs.EncryptionAlgorithmAES256GCM.

root key algorithm is required

Error message

root key algorithm is required

What it means

RootKeyMeta.Validate requires Algorithm to be non-empty. The algorithm determines how the root key is used for encryption (e.g. aes256-gcm), and downstream crypto code cannot proceed without it, so an empty algorithm fails validation.

Source

Thrown at nomad/structs/keyring.go:405

}

func (rkm *RootKeyMeta) Copy() *RootKeyMeta {
	if rkm == nil {
		return nil
	}
	out := *rkm
	return &out
}

func (rkm *RootKeyMeta) Validate() error {
	if rkm == nil {
		return fmt.Errorf("root key metadata is required")
	}
	if rkm.KeyID == "" || !helper.IsUUID(rkm.KeyID) {
		return fmt.Errorf("root key UUID is required")
	}
	if rkm.Algorithm == "" {
		return fmt.Errorf("root key algorithm is required")
	}
	switch rkm.State {
	case RootKeyStateInactive, RootKeyStateActive,
		RootKeyStateRekeying, RootKeyStateDeprecated, RootKeyStatePrepublished:
	default:
		return fmt.Errorf("root key state %q is invalid", rkm.State)
	}
	return nil
}

// KeyEncryptionKeyWrapper is a flattened version of the WrappedRootKeys struct
// that gets serialized to disk for a keyset when using the legacy on-disk
// keystore with the AEAD KMS wrapper. This struct includes the server-specific
// key-wrapping key (KEK). This struct should never be sent over RPC or written
// to Raft.
type KeyEncryptionKeyWrapper struct {
	Meta *RootKeyMeta

View on GitHub (pinned to 482b49bf1a)

Solutions

Set Algorithm to a supported value such as structs.EncryptionAlgorithmAES256GCM.
Use structs.NewRootKeyMeta() which populates a default algorithm and key ID.
Add the algorithm field to your API request JSON if it was omitted.

Example fix

// before
meta := &structs.RootKeyMeta{KeyID: keyID}
// after
meta := &structs.RootKeyMeta{KeyID: keyID, Algorithm: structs.EncryptionAlgorithmAES256GCM}

Defensive patterns

Strategy: validation

Validate before calling

if meta.Algorithm == "" {
    return fmt.Errorf("Algorithm must be set (e.g. structs.EncryptionAlgorithmAES256GCM)")
}

Try / catch

if err := meta.Validate(); err != nil {
    if strings.Contains(err.Error(), "root key algorithm is required") {
        return fmt.Errorf("set RootKeyMeta.Algorithm before upserting a root key")
    }
    return err
}

Prevention

Use structs.NewRootKeyMeta() which sets a default algorithm
Define algorithm constants in one place in your tooling instead of raw strings
When marshaling metadata to JSON, ensure Algorithm has omitempty-free tags or explicit set

When it happens

Trigger: Upserting or rotating a root key where RootKeyMeta.Algorithm was never set (zero-value string) — for example building metadata manually instead of using structs.NewRootKeyMeta which sets a default algorithm.

Common situations: Hand-writing API payloads for /v1/operator/root-key that omit the algorithm field; older clients or scripts predating the algorithm field; copying metadata structs and clearing fields.

Related errors

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