{"record":{"id":"7a8cc127265c0b25","repo":"hashicorp/nomad","slug":"root-key-state-q-is-invalid","errorCode":null,"errorMessage":"root key state %q is invalid","messagePattern":"root key state %q is invalid","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/keyring.go","lineNumber":411,"sourceCode":"\tout := *rkm\n\treturn &out\n}\n\nfunc (rkm *RootKeyMeta) Validate() error {\n\tif rkm == nil {\n\t\treturn fmt.Errorf(\"root key metadata is required\")\n\t}\n\tif rkm.KeyID == \"\" || !helper.IsUUID(rkm.KeyID) {\n\t\treturn fmt.Errorf(\"root key UUID is required\")\n\t}\n\tif rkm.Algorithm == \"\" {\n\t\treturn fmt.Errorf(\"root key algorithm is required\")\n\t}\n\tswitch rkm.State {\n\tcase RootKeyStateInactive, RootKeyStateActive,\n\t\tRootKeyStateRekeying, RootKeyStateDeprecated, RootKeyStatePrepublished:\n\tdefault:\n\t\treturn fmt.Errorf(\"root key state %q is invalid\", rkm.State)\n\t}\n\treturn nil\n}\n\n// KeyEncryptionKeyWrapper is a flattened version of the WrappedRootKeys struct\n// that gets serialized to disk for a keyset when using the legacy on-disk\n// keystore with the AEAD KMS wrapper. This struct includes the server-specific\n// key-wrapping key (KEK). This struct should never be sent over RPC or written\n// to Raft.\ntype KeyEncryptionKeyWrapper struct {\n\tMeta *RootKeyMeta\n\n\tProvider                 string             `json:\"Provider,omitempty\"`\n\tProviderID               string             `json:\"ProviderID,omitempty\"`\n\tWrappedDataEncryptionKey *wrapping.BlobInfo `json:\"WrappedDEK,omitempty\"`\n\tWrappedRSAKey            *wrapping.BlobInfo `json:\"WrappedRSAKey,omitempty\"`\n\tKeyEncryptionKey         []byte             `json:\"KEK,omitempty\"`\n","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/keyring.go#L393-L429","documentation":"RootKeyMeta.Validate checks that State is one of the five recognized lifecycle states: inactive, active, rekeying, deprecated, or prepublished. Any other string (including empty) is rejected with this formatted error that echoes the offending value.","triggerScenarios":"Submitting a root key whose State field is \"\", misspelled (\"actve\"), capitalized (\"Active\"), or a state from a different system; also occurs when older clients send keys without a state field.","commonSituations":"Manual API calls to root-key endpoints with hand-written JSON; scripts importing keys with custom state labels; version skew where the client predates a state value the server accepts.","solutions":["Set State to one of: \"inactive\", \"active\", \"rekeying\", \"deprecated\", or \"prepublished\" (exact lowercase constants in nomad/structs/keyring.go).","Use structs.NewRootKeyMeta() to get a valid default state (inactive/active) instead of hand-building metadata.","Fix casing/typos — the match is exact and case-sensitive."],"exampleFix":"// before\nmeta := &structs.RootKeyMeta{State: \"Active\"}\n// after\nmeta := &structs.RootKeyMeta{State: structs.RootKeyStateActive} // \"active\"","handlingStrategy":"validation","validationCode":"validStates := map[structs.RootKeyState]bool{\n    structs.RootKeyStateInactive: true, structs.RootKeyStateActive: true,\n    structs.RootKeyStateRekeying: true, structs.RootKeyStateDeprecated: true,\n    structs.RootKeyStatePrepublished: true,\n}\nif !validStates[meta.State] {\n    return fmt.Errorf(\"invalid root key state %q\", meta.State)\n}","typeGuard":null,"tryCatchPattern":"if err := meta.Validate(); err != nil {\n    if strings.Contains(err.Error(), \"root key state\") {\n        return fmt.Errorf(\"state must be one of inactive|active|rekeying|deprecated|prepublished: %w\", err)\n    }\n    return err\n}","preventionTips":["Reference structs.RootKeyState* constants, never string literals","Remember state matching is exact and lowercase","Check Nomad version for newly added states when sharing configs across clusters"],"tags":["nomad","keyring","root-key","enum-validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}