aeron-io/aeron · error · UnknownSubscriptionException

unknown subscription

Error message

unknown subscription: {registrationId}

What it means

Thrown when adding a destination to a subscription (non-spy path) but no receiveChannelEndpoint can be resolved for the given subscription registrationId. The driver searched its subscription links for an endpoint matching the id and found none, meaning the subscription is unknown or has no bound channel endpoint.

Solutions

  1. Verify the registrationId belongs to an active network subscription in the same driver instance.
  2. Ensure the subscription was added with a network channel (not spy) so it owns a receiveChannelEndpoint.
  3. Catch UnknownSubscriptionException and re-create the subscription, then add destinations to the new id.
  4. Check driver logs for the subscription close event that invalidated the id.

Example fix

// before
long id = oldClosedSubscription.registrationId();
driverProxy.addRcvDestination(id, destinationChannel); // unknown
// after
long id = aeron.addSubscription("aeron:udp?endpoint=0.0.0.0:40456|control-mode=manual", streamId);
driverProxy.addRcvDestination(id, destinationChannel);
Defensive patterns

Strategy: try-catch

Validate before calling

if (registrationId == 0 || closedSubscriptions.contains(registrationId)) { throw new IllegalStateException("subscription not active"); }

Try / catch

try {
    driverProxy.addRcvDestination(subscriptionId, destination);
} catch (UnknownSubscriptionException e) {
    subscriptionId = aeron.addSubscription(channelUri, streamId);
    driverProxy.addRcvDestination(subscriptionId, destination);
}

Prevention

When it happens

Trigger: Calling addRcvDestination with a registrationId that has no receive channel endpoint in this driver — unknown id, subscription closed, or subscription created with a URI that never created an endpoint (e.g. spy-only).

Common situations: Passing the wrong handle/id after a client reconnect; operating on a subscription closed by another thread; using a spy subscription id for a network destination call.

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/0f7402bed8063c05. Report an issue: GitHub.

Appendix: source

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

            return State.DONE == state;
        }

        private void init()
        {
            for (int i = 0, size = subscriptionLinks.size(); i < size; i++)
            {
                final SubscriptionLink subscriptionLink = subscriptionLinks.get(i);
                if (registrationId == subscriptionLink.registrationId())
                {
                    receiveChannelEndpoint = subscriptionLink.channelEndpoint();
                    break;
                }
            }

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

            receiveChannelEndpoint.validateAllowsDestinationControl();

            parseChannelResult = nativeResourceAgentProxy.parseChannel(destinationChannel, true);

            state = State.AWAITING_CHANNEL_PARSE;
        }

        private void awaitingChannelParse()
        {
            if (null != (udpChannel = parseChannelResult.get()))
            {
                state = State.REMOVING;
            }
        }

        private void removing()

View on GitHub (pinned to 6d60124e15)