{"record":{"id":"cfdf66cf7351e35b","repo":"apache/skywalking","slug":"duplicate-worker-name-remotereceiverworkname","errorCode":null,"errorMessage":"Duplicate worker name:{remoteReceiverWorkName}","messagePattern":"Duplicate worker name:(.+?)","errorType":"exception","errorClass":"UnexpectedException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/worker/WorkerInstancesService.java","lineNumber":50,"sourceCode":"public class WorkerInstancesService implements IWorkerInstanceSetter, IWorkerInstanceGetter {\n    private static final Logger LOGGER = LoggerFactory.getLogger(WorkerInstancesService.class);\n\n    private final Map<String, RemoteHandleWorker> instances;\n\n    public WorkerInstancesService() {\n        this.instances = new HashMap<>();\n    }\n\n    @Override\n    public RemoteHandleWorker get(String nextWorkerName) {\n        return instances.get(nextWorkerName);\n    }\n\n    @Override\n    public void put(String remoteReceiverWorkName, AbstractWorker instance,\n                    MetricStreamKind kind, Class<? extends StreamData> streamDataClass) {\n        if (instances.containsKey(remoteReceiverWorkName)) {\n            throw new UnexpectedException(\"Duplicate worker name:\" + remoteReceiverWorkName);\n        }\n        instances.put(remoteReceiverWorkName, new RemoteHandleWorker(instance, kind, streamDataClass));\n        LOGGER.debug(\"Worker {} has been registered as {}\", instance.toString(), remoteReceiverWorkName);\n    }\n\n    @Override\n    public void remove(String remoteReceiverWorkName) {\n        final RemoteHandleWorker removed = instances.remove(remoteReceiverWorkName);\n        if (removed != null) {\n            LOGGER.debug(\"Worker {} has been deregistered\", remoteReceiverWorkName);\n        }\n    }\n}\n","sourceCodeStart":32,"sourceCodeEnd":64,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/worker/WorkerInstancesService.java#L32-L64","documentation":"WorkerInstancesService.put() registers stream-processor workers (metrics dispatch endpoints) in a name-keyed map used for inter-OAP remote forwarding in cluster mode. Names must be unique process-wide; registering a second worker under an existing remoteReceiverWorkName throws UnexpectedException('Duplicate worker name:...'). It fires during OAP startup when stream pipelines (mostly OAL-generated metrics workers) are wired.","triggerScenarios":"Two stream workers registered with the same worker/dispatch name — typically two OAL metrics producing the same downstream worker name, or a custom metric/OAL rule that collides with an existing one; occurs at boot while put() is called during node role/stream registration (especially with cluster module remote handlers).","commonSituations":"Adding a custom OAL metric whose name duplicates a built-in metric; multiple OAL scripts defining the same metric name; upgrading OAP where a rule file was loaded twice (config includes both old and new rule files); copy-pasting MAL/OAL rules without renaming outputs.","solutions":["Identify the duplicate name in the message and grep your OAL/MAL/LAL rule files for a metric (or dispatcher target) with that name; rename one of them.","Check that rule files are not loaded twice via configuration (e.g. both a packaged rule and a custom override of the same metric).","After upgrading OAP, diff your custom metrics against the newly built-in ones — a rename in core may now collide.","Restart OAP once fixed."],"exampleFix":"// custom.oal — before\nendpoint_qps_5m = from(Endpoint.*).sum()   // collides with built-in worker\n\n// after\nmy_endpoint_qps_5m = from(Endpoint.*).sum()","handlingStrategy":"validation","validationCode":"// CI check: no duplicate output metric names across OAL files\nSet<String> seen = new HashSet<>();\nfor (String metricName : allOalMetricNames()) {\n    if (!seen.add(metricName)) throw new BuildFailure(\"duplicate worker/metric name: \" + metricName);\n}","typeGuard":null,"tryCatchPattern":"Not applicable — fail-fast at startup is desired; rename the colliding metric instead of catching.","preventionTips":["Prefix custom OAL metric names with a project namespace to avoid colliding with built-ins.","Diff custom metrics against built-in OAL after every OAP upgrade.","Ensure each rule file is loaded exactly once (check core config includes)."],"tags":["startup","oal","stream-processing","cluster","configuration","duplicate"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}