alibaba/nacos · error · NacosException
{}
{}
Error message
{} What it means
RpcClient.request() rethrows the server's own error code and message when the transport returns an ErrorResponse (a protobuf Response with a non-zero errorCode). The literal error code/message come straight from the server, so this entry is a generic re-throw surface: the actual meaning is whatever the server-side handler attached. The only special case is UN_REGISTER (301), which additionally triggers an async server switch before rethrowing.
Source
Thrown at common/src/main/java/com/alibaba/nacos/common/remote/client/RpcClient.java:693
if (response == null) {
throw new NacosException(SERVER_ERROR, "Unknown Exception.");
}
if (response instanceof ErrorResponse) {
if (response.getErrorCode() == NacosException.UN_REGISTER) {
synchronized (this) {
waitReconnect = true;
if (rpcClientStatus.compareAndSet(RpcClientStatus.RUNNING,
RpcClientStatus.UNHEALTHY)) {
LoggerUtils.printIfErrorEnabled(LOGGER,
"Connection is unregistered, switch server, connectionId = {}, request = {}",
currentConnection.getConnectionId(),
request.getClass().getSimpleName());
switchServerAsync();
}
}
}
throw new NacosException(response.getErrorCode(), response.getMessage());
}
// return response.
lastActiveTimeStamp = System.currentTimeMillis();
return response;
} catch (Throwable e) {
if (waitReconnect) {
try {
// wait client to reconnect.
Thread.sleep(Math.min(100, timeoutMills / 3));
} catch (Exception exception) {
// Do nothing.
}
}
LoggerUtils.printIfErrorEnabled(LOGGER,
"Send request fail, request = {}, retryTimes = {}, errorMessage = {}", request,
retryTimes,View on GitHub (pinned to 9b989acdf1)
Solutions
- Read the embedded errorCode and message to identify the true cause; the wrapper here only forwards them.
- For UN_REGISTER (301), the client auto-switches servers; allow time for reconnect and retry the request once isRunning() returns true.
- For auth/permission codes, refresh credentials/tokens and verify the user has the required permission on the resource.
- For validation codes, correct the request fields (dataId/group/namespace) per the server message.
Defensive patterns
Strategy: try-catch
Try / catch
try {
response = client.request(req, timeout);
} catch (NacosException ne) {
switch (ne.getErrCode()) {
case NacosException.UN_REGISTER: // 301 — server dropped connection, will reconnect
case NacosException.NO_RIGHT: // auth — refresh token then retry
default: // surface other server error codes per their documented meaning
}
} Prevention
- Branch on getErrCode() to handle each server error category specifically.
- For 301 (UN_REGISTER), allow the auto server-switch to complete before retrying.
- Keep auth tokens fresh to avoid permission-based ErrorResponse codes.
When it happens
Trigger: Any server-side request handler that returns an ErrorResponse — for example permission denied, resource not found, bad request params, or the connection being force-unregistered (301). After the retry loop catches the thrown NacosException it eventually surfaces both code and message verbatim from `response.getErrorCode()` / `response.getMessage()`.
Common situations: Missing or expired access token / no permission (server returns auth error code). Request payload fails server-side validation. Server initiated connection un-registration (overload, restart, duplicate connection). Resource does not exist (config dataId not found, naming service missing).
Related errors
AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14).
Data as JSON: /api/errors/f851f49885259bf4.
Report an issue: GitHub.