aeron-io/aeron · error · IllegalArgumentException

image.correlationId=

Error message

image.correlationId={responseCorrelationId} not found

What it means

Thrown when a client requests an image by responseCorrelationId (response-channel / image correlation) but no existing subscription or image matches that correlationId. The driver looked through its records and found no subscriber that had requested a response channel corresponding to the given correlationId, so it cannot service the request.

Solutions

1. Verify the correlationId matches a currently active image in this driver (check via aeron-stat or the driver's counting counters) before issuing the request.
2. Re-fetch the correlationId from the live publication/publicationParams response after driver restart — ids are not persistent.
3. Ensure ordering: the subscription that requests the response channel must be created before the correlated request.
4. Catch IllegalArgumentException in the client and re-create the subscription/image pair from scratch.

Example fix

// before
client.addSubscription("aeron:udp?endpoint=127.0.0.1:40456|cc=cubic", streamId) // uses stale image.correlationId=42 from old session
// after
long imageCorrelationId = liveImage.correlationId(); // re-read from the active Aeron instance
String channel = "aeron:udp?endpoint=127.0.0.1:40456|image.correlationId=" + imageCorrelationId;

if (imageCorrelationId <= 0 || !activeImages.contains(imageCorrelationId)) { throw new IllegalStateException("correlationId not active: " + imageCorrelationId); }

try {
    addResponseChannelSubscription(imageCorrelationId);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("image.correlationId=" + imageCorrelationId)) {
        refreshImageCorrelationIdAndRetry();
    } else { throw e; }
}

When it happens

Trigger: Calling Aeron APIs that resolve an image by response correlationId (e.g. adding a destination/response channel referencing image.correlationId=...) with a correlationId that was never registered by a prior subscription in this driver instance, or one whose image/subscription has since been closed.

Common situations: Stale or copied correlationIds from a previous driver session; the subscribing publication/image was closed before the response-channel request arrived; typo or mismatch between the correlationId printed in logs and the live one; restarting the driver (all correlationIds are ephemeral).

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 subscription
• unknown MDS subscription
• unknown MDS subscription
• unknown subscription
• EINVAL

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

Appendix: source

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

            for (final PublicationImage publicationImage : publicationImages)
            {
                if (publicationImage.correlationId() == params.responseCorrelationId)
                {
                    if (publicationImage.hasSendResponseSetup())
                    {
                        return publicationImage;
                    }
                    else
                    {
                        throw new IllegalArgumentException(
                            "image.correlationId=" + params.responseCorrelationId +
                                " did not request a response channel");
                    }
                }
            }

            throw new IllegalArgumentException("image.correlationId=" + params.responseCorrelationId + " not found");
        }

        private enum State
        {
            INIT,
            PARSE_CHANNEL,
            VALIDATE,
            RESOLVE_PUBLICATION,
            AWAIT_LOG_BUFFER,
            CREATE_PUBLICATION,
            DONE
        }
    }

    private final class AddIpcPublicationCommand extends ClientCommand
    {
        private final String channel;
        private final int streamId;

View on GitHub (pinned to 6d60124e15)