aeron-io/aeron · error · UnknownSubscriptionException

unknown MDS subscription

Error message

unknown MDS subscription: {registrationId}

What it means

Thrown when adding a spy destination to a Multi-Destination Subscription (MDS) but no subscription link matching the given registrationId exists in the driver. findMdsSubscriptionLink scanned subscriptionLinks and returned null, so the target MDS subscription is unknown.

Solutions

1. Confirm the registrationId is the one returned by the addSubscription call for the multi-destination subscription in the same running driver.
2. Check the subscription is still open (not closed) before adding destinations.
3. Catch UnknownSubscriptionException in the client and re-add the subscription to obtain a fresh registrationId.
4. Use aeron-stat / driver tooling to list active subscriptions and verify the id.

Example fix

// before
long badId = 12345L; // subscription already closed
// after
long mdsId = aeron.addSubscription("aeron:udp?control-mode=manual", streamId); // keep the live id
driverProxy.addRcvDestination(mdsId, spyChannel);

boolean known = subscriptionLinks.stream().anyMatch(l -> l.registrationId() == mdsRegistrationId && l.isMds());
if (!known) { /* re-create subscription before addRcvDestination */ }

try {
    driverProxy.addRcvDestination(mdsId, channel);
} catch (UnknownSubscriptionException e) {
    mdsId = aeron.addSubscription(uri, streamId);
    driverProxy.addRcvDestination(mdsId, channel);
}

When it happens

Trigger: Calling addRcvDestination (spy path) or similar with a registrationId that is not an active MDS subscription: wrong id, subscription already closed, or the id belongs to a normal (non-MDS) subscription.

Common situations: Using the registrationId returned from a different driver instance; racing a closeSubscription with addRcvDestination from another thread/client; mistaking a publication registrationId for a subscription registrationId.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• unknown MDS subscription
• unknown subscription
• image.correlationId=
• unknown subscription
• Driver events adapter is invalid

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/71db00b2f70cc37b. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java:3198

            this.registrationId = registrationId;
            parseChannelResult = nativeResourceAgentProxy.parseChannel(destinationChannel, false);
        }

        boolean execute()
        {
            final UdpChannel udpChannel = parseChannelResult.get();
            if (null == udpChannel)
            {
                return false;
            }

            final SubscriptionParams params =
                SubscriptionParams.getSubscriptionParams(udpChannel.channelUri(), ctx, 0);
            final SubscriptionLink mdsSubscriptionLink = findMdsSubscriptionLink(subscriptionLinks, registrationId);

            if (null == mdsSubscriptionLink)
            {
                throw new UnknownSubscriptionException("unknown MDS subscription: " + registrationId);
            }

            final SpySubscriptionLink subscriptionLink = new SpySubscriptionLink(
                registrationId,
                udpChannel,
                mdsSubscriptionLink.streamId(),
                mdsSubscriptionLink.aeronClient(),
                params);

            subscriptionLinks.add(subscriptionLink);
            clientProxy.operationSucceeded(correlationId);

            for (int i = 0, size = networkPublications.size(); i < size; i++)
            {
                final NetworkPublication publication = networkPublications.get(i);
                if (subscriptionLink.matches(publication) && publication.isAcceptingSubscriptions())
                {
                    clientProxy.onAvailableImage(

View on GitHub (pinned to 6d60124e15)