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

Generate a proper UUID for KeyID, e.g. via helper.GenerateUUID() or uuid.New().

root key UUID is required

Error message

root key UUID is required

What it means

RootKeyMeta.Validate requires the KeyID field to be a non-empty, well-formed UUID (checked via helper.IsUUID). Root keys are identified by this UUID throughout the keyring, state store, and wrapped-key material, so an absent or malformed ID is rejected.

Source

Thrown at nomad/structs/keyring.go:402

// 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
// 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.

View on GitHub (pinned to 482b49bf1a)

Solutions

Generate a proper UUID for KeyID, e.g. via helper.GenerateUUID() or uuid.New().
Ensure the ID string is a canonical 8-4-4-4-12 hex UUID before submitting.
If the key already exists, look it up by its existing UUID rather than inventing a new one.

Example fix

// before
meta := &structs.RootKeyMeta{KeyID: "prod-key-1"}
// after
meta := &structs.RootKeyMeta{KeyID: helper.GenerateUUID()}

Defensive patterns

Strategy: validation

Validate before calling

if meta.KeyID == "" || !helper.IsUUID(meta.KeyID) {
    return fmt.Errorf("KeyID must be a valid UUID, got %q", meta.KeyID)
}

Try / catch

if err := meta.Validate(); err != nil {
    if strings.Contains(err.Error(), "root key UUID is required") {
        meta.KeyID = helper.GenerateUUID()
        err = meta.Validate()
    }
    return err
}

Prevention

Generate key IDs only with helper.GenerateUUID() or uuid.New()
Never hand-write UUIDs in scripts; capture them from keyring list output
Store and reference keys by the server-issued UUID

When it happens

Trigger: Creating or upserting a root key whose KeyID is "" or not a canonical UUID (e.g. "my-key", "1234", or a UUID with wrong formatting/length).

Common situations: Generating keys manually with custom IDs instead of UUIDs; truncating or reformatting UUIDs when copying between systems; client-side key creation that forgot to call the ID generator.

Related errors

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