{"record":{"id":"dcea6b38dae4deb5","repo":"alibaba/nacos","slug":"500-dcea6b","errorCode":"500","errorMessage":"service not found: {groupedServiceName}@{namespaceId}","messagePattern":"service not found: (.+?)@(.+?)","errorType":"exception","errorClass":"NacosException","httpStatus":null,"severity":"critical","filePath":"naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java","lineNumber":264,"sourceCode":"    public int handleBeat(String namespaceId, String groupName, String serviceName, String ip,\n        int port, String cluster,\n        RsInfo clientBeat, BeatInfoInstanceBuilder builder) throws NacosException {\n        Service service = Service.newService(namespaceId, groupName, serviceName, true);\n        String clientId =\n            IpPortBasedClient.getClientId(ip + InternetAddressUtil.IP_PORT_SPLITER + port, true);\n        IpPortBasedClient client = (IpPortBasedClient) clientManager.getClient(clientId);\n        String groupedServiceName = NamingUtils.getGroupedName(serviceName, groupName);\n        if (null == client || !client.getAllPublishedService().contains(service)) {\n            if (null == clientBeat) {\n                return NamingResponseCode.RESOURCE_NOT_FOUND;\n            }\n            Instance instance =\n                builder.setBeatInfo(clientBeat).setServiceName(groupedServiceName).build();\n            registerInstance(namespaceId, groupName, serviceName, instance);\n            client = (IpPortBasedClient) clientManager.getClient(clientId);\n        }\n        if (!ServiceManager.getInstance().containSingleton(service)) {\n            throw new NacosException(NacosException.SERVER_ERROR,\n                \"service not found: \" + groupedServiceName + \"@\" + namespaceId);\n        }\n        if (null == clientBeat) {\n            clientBeat = new RsInfo();\n            clientBeat.setIp(ip);\n            clientBeat.setPort(port);\n            clientBeat.setCluster(cluster);\n            clientBeat.setServiceName(groupedServiceName);\n        }\n        ClientBeatProcessorV2 beatProcessor =\n            new ClientBeatProcessorV2(namespaceId, clientBeat, client);\n        HealthCheckReactor.scheduleNow(beatProcessor);\n        client.setLastUpdatedTime();\n        return NamingResponseCode.OK;\n    }\n    \n    @Override\n    public long getHeartBeatInterval(String namespaceId, String serviceName, String ip, int port,","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java#L246-L282","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before sending beats, confirm the service singleton exists on the server\nboolean exists = ServiceManager.getInstance().containSingleton(\n    Service.newService(namespaceId, groupName, serviceName, true));\nif (!exists) {\n    // create the service first or wait for Distro convergence\n}","typeGuard":null,"tryCatchPattern":"try {\n    int code = instanceOperator.handleBeat(ns, group, svc, ip, port, cluster, beat, builder);\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR\n            && e.getMessage().contains(\"service not found\")) {\n        // server-side inconsistency; retry after a short backoff\n        // or escalate to verify cluster health\n    } else throw e;\n}","preventionTips":["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."],"tags":["naming","server-error","heartbeat","service-manager","internal-consistency"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}