alibaba/nacos · error · NacosRuntimeException

500

500

Error message

unpectedException.getMessage()

What it means

The catch-all fallback of updateUserPassword: any non-NacosException thrown during the proxied password update is rewrapped as NacosRuntimeException(500, cause.getMessage()). This usually indicates the HTTP client threw an unexpected runtime exception, or the response could not be processed — for a fire-and-forget update the typical cause is a network/IO runtime fault.

Source

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

        if (null == user) {
            throw new UsernameNotFoundException(String.format("User %s not found", username));
        }
        return new NacosUserDetails(user);
    }
    
    @Override
    public void updateUserPassword(String username, String password) {
        Query query = Query.newInstance().addParam("username", username);
        Map<String, String> body = Map.of("newPassword", password);
        try {
            HttpRestResult<String> result = nacosRestTemplate.putForm(
                buildRemoteUserUrlPath(AuthConstants.USER_PATH),
                RemoteServerUtil.buildServerRemoteHeader(), query, body, String.class);
            RemoteServerUtil.singleCheckResult(result);
        } catch (NacosException e) {
            throw new NacosRuntimeException(e.getErrCode(), e.getErrMsg());
        } catch (Exception unpectedException) {
            throw new NacosRuntimeException(NacosException.SERVER_ERROR,
                unpectedException.getMessage());
        }
    }
    
    @Override
    public Page<User> getUsers(int pageNo, int pageSize, String username) {
        Query query = Query.newInstance().addParam("username", username).addParam("pageNo", pageNo)
            .addParam("pageSize", pageSize).addParam("search", "accurate");
        return getUserPageFromRemote(query);
    }
    
    @Override
    public Page<User> findUsers(String username, int pageNo, int pageSize) {
        Query query = Query.newInstance().addParam("username", username).addParam("pageNo", pageNo)
            .addParam("pageSize", pageSize).addParam("search", "blur");
        return getUserPageFromRemote(query);
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Read the wrapped message to identify the underlying exception class.
  2. Retry the update once after a short delay for transient network errors.
  3. Verify HTTP client / TLS configuration if SSL-related text appears.
  4. Check the peer is healthy and serving /user.

Example fix

// before
userService.updateUserPassword(username, newPassword);

// after
try {
    userService.updateUserPassword(username, newPassword);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR) {
        log.error("password update infra failure for {}: {}", username, e.getMessage(), e);
    }
    throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight: confirm a peer is configured for the proxied update.
if (RemoteServerUtil.getServerAddresses().isEmpty()) {
    throw new IllegalStateException("no peer configured; password update cannot be proxied");
}

Try / catch

try {
    userService.updateUserPassword(username, newPassword);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR) {
        log.error("password update infra failure: {}", e.getMessage(), e);
        // optionally retry once on transient network faults
    }
    throw e;
}

Prevention

When it happens

Trigger: PUT password update fails with a non-NacosException such as an IllegalStateException from the HTTP client, a NullPointerException, or an uncaught IOException that the client exposed as a runtime error.

Common situations: Transient network glitch during the update; HTTP client misconfigured (SSL, proxy); peer returned a body that broke the client internals.

Related errors

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