PKCS11 HSM support requires a license with the HSM feature e

Error message

PKCS11 HSM support requires a license with the HSM feature enabled: %w

What it means

During auth server startup, NewServer checks that the license carries the HSM entitlement before allowing a PKCS11 KeyStoreConfig. If a PKCS11 HSM is configured but the running modules' features do not enable entitlements.HSM (e.g. OSS or non-HSM Enterprise license), startup fails with this error wrapping ErrRequiresEnterprise.

Source

Thrown at lib/auth/auth.go:286

	}
	if cfg.ClusterConfiguration == nil {
		clusterConfig, err := local.NewClusterConfigurationService(cfg.Backend)
		if err != nil {
			return nil, trace.Wrap(err)
		}
		cfg.ClusterConfiguration = clusterConfig
	}
	if cfg.KeyStore == nil {
		keystoreOpts := &keystore.Options{
			HostUUID:             cfg.HostUUID,
			ClusterName:          cfg.ClusterName,
			AuthPreferenceGetter: cfg.ClusterConfiguration,
			FIPS:                 cfg.FIPS,
			Clock:                cfg.Clock,
		}
		if cfg.KeyStoreConfig.PKCS11 != (servicecfg.PKCS11Config{}) {
			if !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {
				return nil, fmt.Errorf("PKCS11 HSM support requires a license with the HSM feature enabled: %w", ErrRequiresEnterprise)
			}
		} else if cfg.KeyStoreConfig.GCPKMS != (servicecfg.GCPKMSConfig{}) {
			if !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {
				return nil, fmt.Errorf("GCP KMS support requires a license with the HSM feature enabled: %w", ErrRequiresEnterprise)
			}
		} else if cfg.KeyStoreConfig.AWSKMS != nil {
			if !cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {
				return nil, fmt.Errorf("AWS KMS support requires a license with the HSM feature enabled: %w", ErrRequiresEnterprise)
			}
		}
		cfg.KeyStore, err = keystore.NewManager(context.Background(), &cfg.KeyStoreConfig, keystoreOpts)
		if err != nil {
			return nil, trace.Wrap(err)
		}
	}
	if cfg.RecordingEncryption == nil {
		localRecordingEncryption, err := local.NewRecordingEncryptionService(cfg.Backend)
		if err != nil {

View on GitHub (pinned to 1283425b60)

Solutions

Obtain/load an Enterprise license with the HSM entitlement enabled and restart the auth service.
If HSM is not intended, remove the PKCS11 section from key_store configuration and use the default software key store.
Verify with `teleport version` / license diagnostics that the Enterprise modules are actually active (not falling back to OSS).

Example fix

// before (auth_service config)
key_store: { type: pkcs11, module_path: /usr/lib/softhsm.so, pin: "1234", slot: 0 }
// after (OSS fallback) — remove the pkcs11 block
key_store: {}
// or upgrade to Enterprise HSM license and keep the config

Defensive patterns

Strategy: validation

Validate before calling

if cfg.KeyStoreConfig.PKCS11 != (servicecfg.PKCS11Config{}) &&
	!cfg.Modules.Features().GetEntitlement(entitlements.HSM).Enabled {
	return errors.New("PKCS11 key store configured but license lacks HSM entitlement; remove pkcs11 config or upgrade license")
}

Try / catch

srv, err := auth.NewServer(...)
if err != nil {
	if strings.Contains(err.Error(), "PKCS11 HSM support requires a license") {
		// startup-blocked: fix config/license before retrying; do not blindly restart
	}
}

Prevention

Check license entitlements before deploying HSM configs to a cluster.
Ensure the Enterprise license file is present and loading at boot.
Keep HSM key_store settings in environment-specific config overlays applied only where licensed.

When it happens

Trigger: Starting the Teleport auth service with key_store configuration pointing at a PKCS11 HSM (pin/slot/module_path set) while the loaded license lacks the HSM feature entitlement.

Common situations: Running OSS Teleport with an HSM config copied from an Enterprise deployment; an Enterprise license without the HSM add-on; license file not loaded/expired so features default to disabled.

Related errors

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/ccc85805f64d2723. Report an issue: GitHub.