alibaba/nacos · warning · UsernameNotFoundException

User %s not found

Error message

User %s not found

What it means

Implements Spring Security's UserDetailsService.loadUserByUsername for the direct (DB-backed) impl. When the user is not found in the cache — or, with caching disabled, not found via the persistence layer — it throws UsernameNotFoundException. This is the expected signal for 'unknown user' during login, which Spring Security maps to an authentication failure (typically 401).

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/users/NacosUserServiceDirectImpl.java:56

    private final UserPersistService userPersistService;
    
    private final NacosAuthPluginConfigProvider configProvider;
    
    public NacosUserServiceDirectImpl(NacosAuthPluginConfigProvider configProvider,
        UserPersistService userPersistService) {
        super();
        this.userPersistService = userPersistService;
        this.configProvider = configProvider;
    }
    
    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        User user = getCachedUserMap().get(username);
        if (!configProvider.getConfig().isCachingEnabled()) {
            user = getUser(username);
        }
        if (user == null) {
            throw new UsernameNotFoundException(String.format("User %s not found", username));
        }
        return new NacosUserDetails(user);
    }
    
    @Override
    public void updateUserPassword(String username, String password) {
        userPersistService.updateUserPassword(username, PasswordEncoderUtil.encode(password));
    }
    
    @Override
    public Page<User> getUsers(int pageNo, int pageSize, String username) {
        return userPersistService.getUsers(pageNo, pageSize, username);
    }
    
    @Override
    public User getUser(String username) {
        return userPersistService.findUserByUsername(username);
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Confirm the username exists in the users table (or via the /user/list API).
  2. If caching is on and the node just started, wait for the reload() sweep (every 15s) or force a cache refresh.
  3. Map UsernameNotFoundException to a clean 401/invalid-credentials response at the controller boundary.
  4. Check that you are querying the right namespace/environment.

Example fix

// before
UserDetails ud = userService.loadUserByUsername(username); // throws if unknown

// after
try {
    UserDetails ud = userService.loadUserByUsername(username);
} catch (UsernameNotFoundException e) {
    // expected: unknown user -> standard auth failure
    throw new BadCredentialsException("invalid credentials");
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Optional: confirm the user exists before triggering Spring Security auth.
import com.alibaba.nacos.common.utils.StringUtils;

if (StringUtils.isBlank(username)) {
    throw new UsernameNotFoundException("username is blank");
}
// With caching off, this hits the DB directly:
if (userService.getUser(username) == null) {
    throw new UsernameNotFoundException("User " + username + " not found");
}

Try / catch

try {
    UserDetails ud = userService.loadUserByUsername(username);
} catch (UsernameNotFoundException e) {
    // expected for unknown users -> standard auth failure (401)
    throw new org.springframework.security.authentication.BadCredentialsException("invalid credentials");
}

Prevention

When it happens

Trigger: A login attempt with a username that does not exist in the database; caching enabled but the user cache has not yet been populated by reload() and the user genuinely does not exist; the user was deleted between cache refreshes.

Common situations: Typo in the username; a deleted user still referenced by a client; a fresh node whose user cache has not loaded yet.

Related errors

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