{"record":{"id":"caddf7952da88ac1","repo":"aeron-io/aeron","slug":"unknown-mds-subscription-registrationid","errorCode":null,"errorMessage":"unknown MDS subscription: ${registrationId}","messagePattern":"unknown MDS subscription: (.+?)","errorType":"exception","errorClass":"UnknownSubscriptionException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java","lineNumber":1002,"sourceCode":"        else if (destinationChannel.startsWith(SPY_QUALIFIER))\n        {\n            onAddRcvSpyDestination(registrationId, destinationChannel, correlationId);\n        }\n        else\n        {\n            onAddRcvNetworkDestination(registrationId, destinationChannel, correlationId);\n        }\n    }\n\n    void onAddRcvIpcDestination(final long registrationId, final String destinationChannel, final long correlationId)\n    {\n        final SubscriptionParams params =\n            SubscriptionParams.getSubscriptionParams(parseUri(destinationChannel), ctx, 0);\n        final SubscriptionLink mdsSubscriptionLink = findMdsSubscriptionLink(subscriptionLinks, registrationId);\n\n        if (null == mdsSubscriptionLink)\n        {\n            throw new UnknownSubscriptionException(\"unknown MDS subscription: \" + registrationId);\n        }\n\n        final IpcSubscriptionLink subscriptionLink = new IpcSubscriptionLink(\n            registrationId,\n            mdsSubscriptionLink.streamId(),\n            destinationChannel,\n            mdsSubscriptionLink.aeronClient(),\n            params);\n\n        subscriptionLinks.add(subscriptionLink);\n        clientProxy.operationSucceeded(correlationId);\n\n        for (int i = 0, size = ipcPublications.size(); i < size; i++)\n        {\n            final IpcPublication publication = ipcPublications.get(i);\n            if (subscriptionLink.matches(publication) && publication.isAcceptingSubscriptions())\n            {\n                clientProxy.onAvailableImage(","sourceCodeStart":984,"sourceCodeEnd":1020,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java#L984-L1020","documentation":"Thrown by DriverConductor when adding an MDS (multi-destination subscription) destination requires a matching existing MDS subscription link (found via findMdsSubscriptionLink) and none exists for the given registrationId. The command adds an IPC destination to an existing MDS subscription; without the parent MDS subscription the request cannot proceed, so UnknownSubscriptionException is thrown.","triggerScenarios":"Calling Subscription.addDestination (or driver addRcvDestination into spy/ipc) with a registrationId of a subscription that is not an MDS subscription, was already removed, or was never created on this client.","commonSituations":"Attempting to add destinations to a normal (non-MDS) subscription; a typo'd or stale subscription registrationId; adding a destination after the MDS subscription was closed or reaped by keepalive timeout; mixing regular and MDS subscription APIs.","solutions":["Create the subscription with a multi-destination URI (aeron:ipc?alias=...|control-mode=manual or mds) and use THAT subscription's registrationId for addDestination","Confirm the subscription is still open (subscription.isClosed()==false) before adding destinations","Ensure the same Aeron client that created the MDS subscription performs addDestination","Check channel URI: MDS requires manual control mode; a plain subscription created without it won't match findMdsSubscriptionLink"],"exampleFix":"// before\nSubscription s = aeron.addSubscription(\"aeron:ipc\", 1001, handler, idle);\naeron.addDestination(s.registrationId(), \"aeron:ipc?alias=dst\"); // not MDS\n// after\nSubscription mds = aeron.addSubscription(\"aeron:ipc|control-mode=manual\", 1001, handler, idle);\naeron.addDestination(mds.registrationId(), \"aeron:ipc?alias=dst\");","handlingStrategy":"validation","validationCode":"if (subscription.isClosed()) throw new IllegalStateException(\"MDS subscription closed\");\nif (!subscription.channel().contains(\"control-mode=manual\")) throw new IllegalStateException(\"not an MDS subscription\");","typeGuard":"boolean isMdsSubscription(Subscription s) { return s != null && !s.isClosed() && s.channel().contains(\"control-mode=manual\"); }","tryCatchPattern":"// validation strategy: check before addDestination\nif (!isMdsSubscription(subscription)) {\n    throw new IllegalStateException(\"create subscription with multi-destination URI first\");\n}\nsubscription.addDestination(destinationUri);","preventionTips":["Create MDS subscriptions with control-mode=manual in the channel URI","Use the MDS subscription's registrationId for destination add/remove calls","Verify subscription.isClosed()==false before mutating destinations","Keep destination mutation on the owning client's lifecycle"],"tags":["aeron","driver","mds","subscription","destination"],"backgroundTag":"resource-not-found","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}