aeron-io/aeron · error · ArchiveException

failed to send get start position request

Error message

failed to send get start position request

What it means

AeronArchive.getStartPosition() throws this ArchiveException when the get-start-position request could not be sent to the archive control-request publication. archiveProxy.getStartPosition() returned false, meaning the offer failed because the publication is not connected, has been closed, or was back-pressured throughout the proxy's retry window, so pollForResponse never runs.

Solutions

1. Verify archive availability and matching control-channel configuration (endpoint, aeron.dir).
2. Retry getStartPosition with backoff; transient back-pressure is the most common cause.
3. Recreate the archive session with AeronArchive.connect() if the control session died.
4. Rate-limit position polling loops to keep the control publication from saturating.
5. Inspect archive-side logs for the session close or publication failure that caused the rejected offer.

if (!archive.archiveProxy().controlPublication().isConnected()) {
    throw new IllegalStateException("archive control publication not connected");
}

try {
    long start = archive.getStartPosition(recordingId);
} catch (ArchiveException e) {
    if (e.getMessage().contains("failed to send get start position request")) {
        Thread.sleep(backoffMs); // retry or reconnect
    } else { throw e; }
}

When it happens

Trigger: Calling getStartPosition(recordingId) when the archive is unreachable, the control session has been closed or timed out, the control publication's terminal buffer is full of unsent commands, or the control channel configuration is wrong.

Common situations: Position lookups during archive restarts or failover; clients holding an archive session past the archive's session timeout; monitoring loops polling start positions faster than the control stream drains.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• failed to send get recording position request
• failed to send get stop position request
• failed to send get max recorded position request
• failed to send list recordings request
• failed to send list recording request

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:1522

     * Get the start position for a recording.
     *
     * @param recordingId of the recording for which the position is required.
     * @return the start position of a recording.
     * @see #getStopPosition(long)
     */
    public long getStartPosition(final long recordingId)
    {
        lock.lock();
        try
        {
            ensureConnected();
            ensureNotReentrant();

            lastCorrelationId = aeron.nextCorrelationId();

            if (!archiveProxy.getStartPosition(recordingId, lastCorrelationId, controlSessionId))
            {
                throw new ArchiveException("failed to send get start position request");
            }

            return pollForResponse(lastCorrelationId);
        }
        finally
        {
            lock.unlock();
        }
    }

    /**
     * Get the position recorded for an active recording. If no active recording then return {@link #NULL_POSITION}.
     *
     * @param recordingId of the active recording for which the position is required.
     * @return the recorded position for the active recording or {@link #NULL_POSITION} if recording not active.
     * @see #getStopPosition(long)
     */
    public long getRecordingPosition(final long recordingId)

View on GitHub (pinned to 6d60124e15)