{"record":{"id":"f25001633e42f823","repo":"hashicorp/nomad","slug":"unknown-keyring-provider-q","errorCode":null,"errorMessage":"unknown keyring provider: %q","messagePattern":"unknown keyring provider: %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/keyring.go","lineNumber":316,"sourceCode":"\t// ExtraKeysHCL gets used by HCL to surface unknown keys. The parser will\n\t// then read these keys to create the Config map, so that we don't need a\n\t// nested \"config\" block/map in the config file\n\tExtraKeysHCL []string `hcl:\",unusedKeys\" json:\"-\"`\n}\n\n// Validate checks that the KEKProviderConfig is valid.\nfunc (c *KEKProviderConfig) Validate() error {\n\n\tif c == nil {\n\t\treturn nil\n\t}\n\n\tswitch c.Provider {\n\tcase KEKProviderAEAD, KEKProviderAWSKMS, KEKProviderAzureKeyVault,\n\t\tKEKProviderGCPCloudKMS, KEKProviderVaultTransit:\n\t\treturn nil\n\tdefault:\n\t\treturn fmt.Errorf(\"unknown keyring provider: %q\", c.Provider)\n\t}\n}\n\nfunc (c *KEKProviderConfig) Copy() *KEKProviderConfig {\n\treturn &KEKProviderConfig{\n\t\tProvider: c.Provider,\n\t\tActive:   c.Active,\n\t\tName:     c.Name,\n\t\tConfig:   maps.Clone(c.Config),\n\t}\n}\n\n// Merge is used to merge two configurations. Note that Provider and Name should\n// always be identical before we merge.\nfunc (c *KEKProviderConfig) Merge(o *KEKProviderConfig) *KEKProviderConfig {\n\tresult := c.Copy()\n\tresult.Active = o.Active\n\tmaps.Copy(result.Config, o.Config)","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/keyring.go#L298-L334","documentation":"KEKProviderConfig.Validate rejects any Provider value that is not one of the five supported key-encryption-key providers (aead, awskms, azurekeyvault, gcpcloudkms, vault-transit). Nomad's keyring wraps root keys with a KEK provider, so an unrecognized provider name makes the config invalid before any key material is touched. This is a pure configuration validation error thrown by the structs package.","triggerScenarios":"Submitting a Keyring or key metadata config whose KEKProviderConfig.Provider is empty, misspelled, or from another tool (e.g. \"kms\", \"vault\", \"aead-kms\"). Occurs when the config is parsed/validated on job or agent configuration submission.","commonSituations":"Typos in the provider name; copying HashiCorp Vault or Consul config that uses different provider strings; forgetting to set provider at all; running a config written for a newer Nomad version against an older binary that lacks a newly added provider.","solutions":["Set Provider to one of the exact supported values: \"aead\", \"awskms\", \"azurekeyvault\", \"gcpcloudkms\", or \"vault-transit\" (verify exact constants in nomad/structs/keyring.go).","Fix the typo/case in the provider name in your agent or keyring config (providers are matched exactly).","If using a provider added in a newer Nomad release, upgrade the Nomad binary to a version that supports it."],"exampleFix":"// before\nkek_provider {\n  provider = \"vault\"\n}\n// after\nkek_provider {\n  provider = \"vault-transit\"\n}","handlingStrategy":"validation","validationCode":"var validProviders = map[string]bool{\"aead\": true, \"awskms\": true, \"azurekeyvault\": true, \"gcpcloudkms\": true, \"vault-transit\": true}\nif !validProviders[cfg.KEKProviderConfig.Provider] {\n    return fmt.Errorf(\"unsupported KEK provider %q\", cfg.KEKProviderConfig.Provider)\n}\nerr := cfg.KEKProviderConfig.Validate()","typeGuard":null,"tryCatchPattern":"if err := kekCfg.Validate(); err != nil {\n    if strings.Contains(err.Error(), \"unknown keyring provider\") {\n        return fmt.Errorf(\"config error: %w (allowed: aead, awskms, azurekeyvault, gcpcloudkms, vault-transit)\", err)\n    }\n    return err\n}","preventionTips":["Copy provider names directly from nomad/structs/keyring.go constants instead of typing from memory","Validate agent config at startup with nomad agent config validation before deployment","Pin Nomad binary version and check provider support in changelogs when upgrading configs"],"tags":["nomad","keyring","configuration","validation"],"backgroundTag":"invalid-provider-config","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"}