What causes "unknown MDS subscription: ${registrationId}" in aeron-io/aeron?

Create the subscription with a multi-destination URI (aeron:ipc?alias=...|control-mode=manual or mds) and use THAT subscription's registrationId for addDestination

aeron-io/aeron · error · UnknownSubscriptionException

unknown MDS subscription

Error message

unknown MDS subscription: ${registrationId}

What it means

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.

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

Example fix

// before
Subscription s = aeron.addSubscription("aeron:ipc", 1001, handler, idle);
aeron.addDestination(s.registrationId(), "aeron:ipc?alias=dst"); // not MDS
// after
Subscription mds = aeron.addSubscription("aeron:ipc|control-mode=manual", 1001, handler, idle);
aeron.addDestination(mds.registrationId(), "aeron:ipc?alias=dst");

Defensive patterns

Strategy: validation

Validate before calling

if (subscription.isClosed()) throw new IllegalStateException("MDS subscription closed");
if (!subscription.channel().contains("control-mode=manual")) throw new IllegalStateException("not an MDS subscription");

Type guard

boolean isMdsSubscription(Subscription s) { return s != null && !s.isClosed() && s.channel().contains("control-mode=manual"); }

Try / catch

// validation strategy: check before addDestination
if (!isMdsSubscription(subscription)) {
    throw new IllegalStateException("create subscription with multi-destination URI first");
}
subscription.addDestination(destinationUri);

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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

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

Appendix: source

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

        else if (destinationChannel.startsWith(SPY_QUALIFIER))
        {
            onAddRcvSpyDestination(registrationId, destinationChannel, correlationId);
        }
        else
        {
            onAddRcvNetworkDestination(registrationId, destinationChannel, correlationId);
        }
    }

    void onAddRcvIpcDestination(final long registrationId, final String destinationChannel, final long correlationId)
    {
        final SubscriptionParams params =
            SubscriptionParams.getSubscriptionParams(parseUri(destinationChannel), ctx, 0);
        final SubscriptionLink mdsSubscriptionLink = findMdsSubscriptionLink(subscriptionLinks, registrationId);

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

        final IpcSubscriptionLink subscriptionLink = new IpcSubscriptionLink(
            registrationId,
            mdsSubscriptionLink.streamId(),
            destinationChannel,
            mdsSubscriptionLink.aeronClient(),
            params);

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

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

View on GitHub (pinned to 6d60124e15)