aeron-io/aeron · error · std::logic_error

index out of range

Error message

index out of range

What it means

Subscription::imageByIndex() delegates to the C API aeron_subscription_image_at_index(), and throws std::logic_error when no image exists at the requested index. It means the caller asked for an image position outside the current image list (0..imageCount()-1), or the image at that position has since gone away.

Solutions

1. Read subscription->imageCount() immediately before the loop and iterate with i < imageCount().
2. Prefer imageBySessionId(sessionId) or the image list snapshot API instead of raw indices when possible.
3. Wrap the call in try/catch (std::logic_error) and skip/re-fetch if the image set changed concurrently.
4. Re-query the subscription after any connection change event before indexing.

Example fix

// before
for (size_t i = 0; i <= sub->imageCount(); ++i)
    auto img = sub->imageByIndex(i);
// after
const size_t n = sub->imageCount();
for (size_t i = 0; i < n; ++i)
    auto img = sub->imageByIndex(i);

bool validIndex(const std::shared_ptr<aeron::Subscription>& sub, size_t i) {
    return i < sub->imageCount();
}

try {
    auto image = sub->imageByIndex(i);
} catch (const std::logic_error& e) {
    // image set changed or index invalid: re-fetch imageCount() and retry/skip
}

When it happens

Trigger: Calling subscription->imageByIndex(i) with i >= subscription->imageCount(), or with a stale index after the number of images changed (image connected/disconnected between calls).

Common situations: Iterating with a cached count that is stale after a channel re-resolution or peer disconnect; off-by-one loops (<= imageCount()); assuming index equals session-id or a stable handle across image lifecycle changes.

Related errors

• EINVAL
• EINVAL
• failed to write reject image command
• position out of range: -
• position not aligned to FRAME_ALIGNMENT

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

Appendix: source

Thrown at aeron-client/src/main/cpp_wrapper/Subscription.h:542

        return createImage(image);
    }

    /**
     * Return the {@link Image} associated with the given index.
     *
     * This method returns a share_ptr to the underlying Image and must be released before the Image may be fully
     * reclaimed.
     *
     * @param index in the array
     * @return image at given index or exception if out of range.
     */
    inline std::shared_ptr<Image> imageByIndex(std::size_t index) const
    {
        aeron_image_t *image = aeron_subscription_image_at_index(m_subscription, index);
        if (nullptr == image)
        {
            throw std::logic_error("index out of range");
        }

        return createImage(image);
    }

    /**
     * Get a std::vector of active std::shared_ptr of {@link Image}s that match this subscription.
     *
     * This method will create a new std::vector<std::shared_ptr<Image>> populated with the underlying {@link Image}s.
     *
     * @return a std::vector of active std::shared_ptr of {@link Image}s that match this subscription
     */
    inline std::shared_ptr<std::vector<std::shared_ptr<Image>>> copyOfImageList() const
    {
        auto images = std::make_shared<std::vector<std::shared_ptr<Image>>>();
        auto subscriptionAndImages = std::make_pair(m_subscription, images.get());

        aeron_subscription_for_each_image(

View on GitHub (pinned to 6d60124e15)