{"record":{"id":"023fd32fd2f09332","repo":"hashicorp/nomad","slug":"unable-to-create-kms-wrapper-for-provider-q-w","errorCode":null,"errorMessage":"unable to create KMS wrapper for provider %q: %w","messagePattern":"unable to create KMS wrapper for provider %q: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/encrypter.go","lineNumber":487,"sourceCode":"\n\tfor _, wrappedKey := range wrappedKeys.WrappedKeys {\n\t\tproviderID := wrappedKey.ProviderID\n\t\tif providerID == \"\" {\n\t\t\tproviderID = string(structs.KEKProviderAEAD)\n\t\t}\n\n\t\tprovider, ok := e.providerConfigs[providerID]\n\t\tif !ok {\n\t\t\terr := fmt.Errorf(\"no such KMS provider %q configured\", providerID)\n\t\t\tmErr = multierror.Append(mErr, err)\n\t\t\tcontinue\n\t\t}\n\n\t\twrapper, err := e.newKMSWrapper(provider, wrappedKeys.KeyID, wrappedKey.KeyEncryptionKey)\n\t\tif err != nil {\n\t\t\t// the errors that bubble up from this library can be a bit opaque, so\n\t\t\t// make sure we wrap them with as much context as possible\n\t\t\terr := fmt.Errorf(\"unable to create KMS wrapper for provider %q: %w\", providerID, err)\n\t\t\tmErr = multierror.Append(mErr, err)\n\t\t\tcontinue\n\t\t}\n\n\t\t// fan-out decryption tasks for HA in Nomad Enterprise. we can use the\n\t\t// key whenever any one provider returns a successful decryption.\n\t\tgo e.decryptWrappedKeyTask(completeCtx, wrapper, wrappedKeys.Meta(), wrappedKey, cipherSetCh)\n\t\tdecryptTasks++\n\t}\n\n\tif err := mErr.ErrorOrNil(); err != nil {\n\n\t\t// If we have no tasks running, we can log an error for the operator and\n\t\t// exit.\n\t\t//\n\t\t// It is likely any decryption configuration for the key is incorrect\n\t\t// and follow-up attempts from other Raft/FMS calls for this key will\n\t\t// also fail. We should not, however, continue with the server startup","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/encrypter.go#L469-L505","documentation":"A matching KMS provider config exists, but newKMSWrapper could not construct the go-kms-wrapping wrapper for it — bad credentials, missing required fields, or failed backend initialization. The underlying error is deliberately wrapped with the provider ID because raw library errors are opaque.","triggerScenarios":"AddWrappedKey resolves the provider config and calls e.newKMSWrapper(provider, wrappedKeys.KeyID, wrappedKey.KeyEncryptionKey); wrapper construction fails on missing/invalid options (e.g. no kms_key_id, invalid Vault token, bad GCP/Azure credentials).","commonSituations":"Incomplete kms block in server config, expired Vault token for transit, IAM credentials not present on the server host, wrong region/endpoint, or env vars (AWS_*, GOOGLE_*, AZURE_*) absent in the agent's environment.","solutions":["Read the wrapped cause (%w) for the specific library error from the KMS SDK","Validate the provider's required fields in the kms config block (kms_key_id, endpoint, region, etc.)","Check cloud credentials on the server (instance profile, env vars, workload identity) and Vault token validity for transit","Test the provider independently (aws kms describe-key, vault status) then restart the agent"],"exampleFix":"// before: kms block missing kms_key_id\nkms = { provider = \"awskms\" region = \"us-east-1\" }\n// after\nkms = {\n  provider   = \"awskms\"\n  kms_key_id = \"alias/nomad-key\"\n  region     = \"us-east-1\"\n}","handlingStrategy":"validation","validationCode":"// smoke-test the provider before the agent needs it\n// awskms: aws kms describe-key --key-id alias/nomad-key --region us-east-1\n// transit: vault token lookup  &&  vault status\n// gcpckms: gcloud kms keys describe nomad-key --keyring=... --location=...\nif err := probeProvider(\"awskms\"); err != nil {\n  return fmt.Errorf(\"KMS provider unreachable, wrapper creation would fail: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := srv.AddWrappedKey(wrappedKeys); err != nil {\n  if strings.Contains(err.Error(), \"unable to create KMS wrapper\") {\n    return fmt.Errorf(\"check KMS credentials and required config fields for this provider, then restart agent: %w\", err)\n  }\n  return err\n}","preventionTips":["Set every required field for the chosen provider (kms_key_id, region, endpoint) in the kms block","Ensure cloud credentials are present in the agent's environment (instance profile, env vars, workload identity)","Use renewable Vault tokens/AppRole for the transit provider","Run a provider smoke test (describe-key / vault status) before agent startup in CI and ops runbooks"],"tags":["kms","wrapper","configuration","credentials","go"],"backgroundTag":"kms-wrapper-init-failed","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"}