alibaba/nacos · critical · NacosException

500

500

Error message

service not found: {groupedServiceName}@{namespaceId}

What it means

Thrown by handleBeat after the heartbeat/beat-registration path completes: the beat handler auto-registered the instance if needed, but ServiceManager still does not contain a singleton for the service. Error code is NacosException.SERVER_ERROR (500), an internal-consistency violation indicating the CP/Distro store and the in-memory ServiceManager are out of sync. This is not a client error — it signals a server-side state problem.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java:264

    public int handleBeat(String namespaceId, String groupName, String serviceName, String ip,
        int port, String cluster,
        RsInfo clientBeat, BeatInfoInstanceBuilder builder) throws NacosException {
        Service service = Service.newService(namespaceId, groupName, serviceName, true);
        String clientId =
            IpPortBasedClient.getClientId(ip + InternetAddressUtil.IP_PORT_SPLITER + port, true);
        IpPortBasedClient client = (IpPortBasedClient) clientManager.getClient(clientId);
        String groupedServiceName = NamingUtils.getGroupedName(serviceName, groupName);
        if (null == client || !client.getAllPublishedService().contains(service)) {
            if (null == clientBeat) {
                return NamingResponseCode.RESOURCE_NOT_FOUND;
            }
            Instance instance =
                builder.setBeatInfo(clientBeat).setServiceName(groupedServiceName).build();
            registerInstance(namespaceId, groupName, serviceName, instance);
            client = (IpPortBasedClient) clientManager.getClient(clientId);
        }
        if (!ServiceManager.getInstance().containSingleton(service)) {
            throw new NacosException(NacosException.SERVER_ERROR,
                "service not found: " + groupedServiceName + "@" + namespaceId);
        }
        if (null == clientBeat) {
            clientBeat = new RsInfo();
            clientBeat.setIp(ip);
            clientBeat.setPort(port);
            clientBeat.setCluster(cluster);
            clientBeat.setServiceName(groupedServiceName);
        }
        ClientBeatProcessorV2 beatProcessor =
            new ClientBeatProcessorV2(namespaceId, clientBeat, client);
        HealthCheckReactor.scheduleNow(beatProcessor);
        client.setLastUpdatedTime();
        return NamingResponseCode.OK;
    }
    
    @Override
    public long getHeartBeatInterval(String namespaceId, String serviceName, String ip, int port,

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure the service is explicitly created (POST to the service creation API) before clients send heartbeats, so the singleton exists.
Check that this server node owns the service shard — if using Distro, verify cluster membership and data sync health.
Increase emptyServiceExpiredTime (nacos.naming.empty.service.expired.time) if empty services are being cleaned too aggressively between beats.
Review server logs for Distro/CProcol sync failures and restart the affected node if the store is corrupted.

Defensive patterns

Strategy: retry

Validate before calling

// Before sending beats, confirm the service singleton exists on the server
boolean exists = ServiceManager.getInstance().containSingleton(
    Service.newService(namespaceId, groupName, serviceName, true));
if (!exists) {
    // create the service first or wait for Distro convergence
}

Try / catch

try {
    int code = instanceOperator.handleBeat(ns, group, svc, ip, port, cluster, beat, builder);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR
            && e.getMessage().contains("service not found")) {
        // server-side inconsistency; retry after a short backoff
        // or escalate to verify cluster health
    } else throw e;
}

Prevention

Explicitly create services before clients start sending heartbeats.
Monitor Distro/CProtocol sync health and empty-service cleanup timing.
Ensure the node receiving the beat owns the service's data shard.

When it happens

Trigger: A client sends a heartbeat (handleBeat) for a service. The IpPortBasedClient is null or does not publish the service, so the beat handler auto-registers the instance. Immediately after, ServiceManager.getInstance().containSingleton(service) returns false because the service singleton was never created (the metadata create event has not propagated, or the service was never explicitly created as a persistent singleton).

Common situations: Server restart or leader failover during which the service singleton was evicted but the client is still sending beats. A race between empty-service cleanup and heartbeat arrival. The service was created transiently (ephemeral) and the Distro data has not yet converged on this node. Misconfigured cluster where this node is not the owner of the service's data shard.

Related errors

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