hashicorp/nomad · error

unknown keyring provider: %q

Error message

unknown keyring provider: %q

What it means

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.

Source

Thrown at nomad/structs/keyring.go:316

	// ExtraKeysHCL gets used by HCL to surface unknown keys. The parser will
	// then read these keys to create the Config map, so that we don't need a
	// nested "config" block/map in the config file
	ExtraKeysHCL []string `hcl:",unusedKeys" json:"-"`
}

// Validate checks that the KEKProviderConfig is valid.
func (c *KEKProviderConfig) Validate() error {

	if c == nil {
		return nil
	}

	switch c.Provider {
	case KEKProviderAEAD, KEKProviderAWSKMS, KEKProviderAzureKeyVault,
		KEKProviderGCPCloudKMS, KEKProviderVaultTransit:
		return nil
	default:
		return fmt.Errorf("unknown keyring provider: %q", c.Provider)
	}
}

func (c *KEKProviderConfig) Copy() *KEKProviderConfig {
	return &KEKProviderConfig{
		Provider: c.Provider,
		Active:   c.Active,
		Name:     c.Name,
		Config:   maps.Clone(c.Config),
	}
}

// Merge is used to merge two configurations. Note that Provider and Name should
// always be identical before we merge.
func (c *KEKProviderConfig) Merge(o *KEKProviderConfig) *KEKProviderConfig {
	result := c.Copy()
	result.Active = o.Active
	maps.Copy(result.Config, o.Config)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set Provider to one of the exact supported values: "aead", "awskms", "azurekeyvault", "gcpcloudkms", or "vault-transit" (verify exact constants in nomad/structs/keyring.go).
2. Fix the typo/case in the provider name in your agent or keyring config (providers are matched exactly).
3. If using a provider added in a newer Nomad release, upgrade the Nomad binary to a version that supports it.

Example fix

// before
kek_provider {
  provider = "vault"
}
// after
kek_provider {
  provider = "vault-transit"
}

var validProviders = map[string]bool{"aead": true, "awskms": true, "azurekeyvault": true, "gcpcloudkms": true, "vault-transit": true}
if !validProviders[cfg.KEKProviderConfig.Provider] {
    return fmt.Errorf("unsupported KEK provider %q", cfg.KEKProviderConfig.Provider)
}
err := cfg.KEKProviderConfig.Validate()

if err := kekCfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "unknown keyring provider") {
        return fmt.Errorf("config error: %w (allowed: aead, awskms, azurekeyvault, gcpcloudkms, vault-transit)", err)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Reschedule policy has unlimited attempts enabled and a low d
• Lock delay and TTL must be positive
• https_handshake_timeout must be >= 0
• http_max_conns_per_client must be >= 0
• Invalid key: %s

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