hashicorp/nomad · error

root key metadata is required

Error message

root key metadata is required

What it means

RootKeyMeta.Validate returns this error when the RootKeyMeta pointer itself is nil. Root key metadata (key ID, algorithm, state) must always accompany root key operations, so a nil metadata object is rejected outright. It is the first check in the validation chain, before UUID/algorithm/state checks.

Source

Thrown at nomad/structs/keyring.go:399

}

// IsInactive indicates that this key is no longer being used to encrypt new
// variables or workload identities.
func (rkm *RootKeyMeta) IsInactive() bool {
	return rkm.State == RootKeyStateInactive || rkm.State == RootKeyStateDeprecated
}

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Construct and pass a valid RootKeyMeta (use structs.NewRootKeyMeta or similar constructor) before calling the keyring API.
2. Check for nil after any decode/deserialize step before invoking Validate or the RPC.
3. Verify the API request body actually includes the root key metadata fields.

Example fix

// before
var meta *structs.RootKeyMeta
err := meta.Validate() // panics/errors: nil
// after
meta := structs.NewRootKeyMeta()
err := meta.Validate()

if meta == nil {
    meta = structs.NewRootKeyMeta()
}
if err := meta.Validate(); err != nil {
    return err
}

func rootKeyMetaIsPresent(m *structs.RootKeyMeta) bool {
    return m != nil
}

if err := meta.Validate(); err != nil {
    if err.Error() == "root key metadata is required" {
        return fmt.Errorf("caller bug: RootKeyMeta must be initialized before keyring RPC")
    }
    return err
}

When it happens

Trigger: Calling keyring APIs (e.g. UPSERT/DELETE root key RPCs, keyring rotation, state store writes) with a nil *RootKeyMeta — typically when a caller forgets to construct metadata or a decode step produced a nil object.

Common situations: Hand-crafting API requests to /v1/operator/root-key endpoints and omitting the metadata; programmatic key rotation where RootKeyMeta was never initialized; decoding an empty/partial response and passing it onward.

Related errors

• root key material is required
• root key algorithm cannot be changed after a key is created
• active root key cannot be deleted - call rotate first
• root key UUID is required
• root key algorithm is required

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