What causes "Required config missing: token.secret.key" in alibaba/nacos?

Generate a base64 secret key of at least 32 bytes: openssl rand -base64 32 (or 64 for HS512).

alibaba/nacos · critical · IllegalArgumentException

Required config missing: token.secret.key

Error message

Required config missing: token.secret.key

What it means

Thrown by NacosAuthPluginConfig.from() when token authentication is required (any auth plugin enabled via NacosAuthConfigHolder.isAnyAuthEnabled()) but the 'token.secret.key' configuration resolves to a blank value. The default for token.secret.key is an empty string (AuthConstants.DEFAULT_TOKEN_SECRET_KEY = ""), so merely enabling auth without explicitly setting a secret key triggers this. It is an IllegalArgumentException raised during applyConfig at server startup or config reload.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/configuration/NacosAuthPluginConfig.java:95

    public static NacosAuthPluginConfig defaults() {
        return new NacosAuthPluginConfig(AuthConstants.DEFAULT_TOKEN_SECRET_KEY,
            AuthConstants.DEFAULT_TOKEN_EXPIRE_SECONDS, DEFAULT_TOKEN_CACHE_ENABLE,
            DEFAULT_CACHING_ENABLED, DEFAULT_ANONYMOUS_AI_ENABLED);
    }
    
    /**
     * Parse and validate one effective plugin configuration map.
     *
     * @param config effective configuration
     * @param tokenSecretRequired whether current module configuration requires token support
     * @return parsed immutable configuration
     */
    public static NacosAuthPluginConfig from(Map<String, String> config,
        boolean tokenSecretRequired) {
        String tokenSecretKey = value(config, TOKEN_SECRET_KEY,
            AuthConstants.DEFAULT_TOKEN_SECRET_KEY);
        if (tokenSecretRequired && StringUtils.isBlank(tokenSecretKey)) {
            throw new IllegalArgumentException("Required config missing: " + TOKEN_SECRET_KEY);
        }
        validateTokenSecret(tokenSecretKey);
        long tokenExpireSeconds = parsePositiveLong(value(config, TOKEN_EXPIRE_SECONDS,
            AuthConstants.DEFAULT_TOKEN_EXPIRE_SECONDS.toString()), TOKEN_EXPIRE_SECONDS);
        boolean tokenCacheEnabled = parseBoolean(value(config, TOKEN_CACHE_ENABLE,
            Boolean.toString(DEFAULT_TOKEN_CACHE_ENABLE)), TOKEN_CACHE_ENABLE);
        boolean cachingEnabled = parseBoolean(value(config, CACHING_ENABLED,
            Boolean.toString(DEFAULT_CACHING_ENABLED)), CACHING_ENABLED);
        boolean anonymousAiEnabled = parseBoolean(value(config, ANONYMOUS_AI_ENABLED,
            Boolean.toString(DEFAULT_ANONYMOUS_AI_ENABLED)), ANONYMOUS_AI_ENABLED);
        return new NacosAuthPluginConfig(tokenSecretKey, tokenExpireSeconds, tokenCacheEnabled,
            cachingEnabled, anonymousAiEnabled);
    }
    
    private static String value(Map<String, String> config, String key, String defaultValue) {
        if (config == null || !config.containsKey(key)) {
            return defaultValue;
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Generate a base64 secret key of at least 32 bytes: openssl rand -base64 32 (or 64 for HS512).
Set nacos.core.auth.plugin.nacos.token.secret.key=<generated-key> in the server's custom.properties / application.properties (or via the console plugin-config UI).
Restart (or re-apply config through the console) so applyConfig() re-parses with a non-blank key.

Example fix

// before (application.properties)
nacos.core.auth.enabled=true
# token.secret.key missing -> error 1260 at boot

// after
nacos.core.auth.enabled=true
nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

Defensive patterns

Strategy: validation

Validate before calling

// Before enabling auth / applying config, ensure a non-blank secret key is present.
String key = effectiveConfig.get(NacosAuthPluginConfig.TOKEN_SECRET_KEY);
boolean authEnabled = NacosAuthConfigHolder.getInstance().isAnyAuthEnabled();
if (authEnabled && StringUtils.isBlank(key)) {
    throw new IllegalStateException(
        "Refusing to apply config: token.secret.key is blank while auth is enabled. "
        + "Generate one with: openssl rand -base64 64");
}
NacosAuthPluginConfig.from(effectiveConfig, authEnabled);

Try / catch

try {
    NacosAuthPluginConfig.from(effectiveConfig, authEnabled);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("token.secret.key")) {
        log.error("Auth enabled but token.secret.key missing/blank; boot will fail until set");
    }
    throw e;
}

Prevention

Add a startup preflight check that fails fast with a clear message when auth is enabled but token.secret.key is blank.
Document the openssl rand -base64 64 generation step next to the auth.enable property.
Store the secret key in a secret manager / env var rather than committing it to the repo.

When it happens

Trigger: Server boots with nacos.core.auth.enabled=true (or any auth plugin enabled) but nacos.core.auth.plugin.nacos.token.secret.key is unset/blank. NacosAuthPluginService.applyConfig() calls NacosAuthPluginConfig.from(effectiveConfig, true); the value() helper returns the empty-string default, StringUtils.isBlank passes, and the throw fires.

Common situations: Enabling Nacos auth for the first time after an upgrade without generating a secret key; setting nacos.core.auth.enabled=true in application.properties but forgetting the token.secret.key property; copying a config file that has the key commented out.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/01bfb18b570eb805. Report an issue: GitHub.