{"record":{"id":"78ffeed32797bc6e","repo":"aeron-io/aeron","slug":"errormessage-correlationid-correlationid-messagetimeout","errorCode":null,"errorMessage":"<errorMessage> - correlationId=<correlationId> messageTimeout=<formattedDuration>","messagePattern":"<errorMessage> - correlationId=<correlationId> messageTimeout=<formattedDuration>","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2350,"sourceCode":"\n            if (!archiveProxy.updateChannel(recordingId, newChannel, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send update channel request\");\n            }\n\n            pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    private void checkDeadline(final long deadlineNs, final String errorMessage, final long correlationId)\n    {\n        if (deadlineNs - nanoClock.nanoTime() < 0)\n        {\n            throw new TimeoutException(\n                errorMessage + \" - correlationId=\" + correlationId + \" messageTimeout=\" +\n                SystemUtil.formatDuration(messageTimeoutNs));\n        }\n\n        if (Thread.currentThread().isInterrupted())\n        {\n            throw new AeronException(\"unexpected interrupt\");\n        }\n    }\n\n    private void pollNextResponse(final long correlationId, final long deadlineNs, final ControlResponsePoller poller)\n    {\n        idleStrategy.reset();\n\n        while (true)\n        {\n            final int fragments = poller.poll();\n","sourceCodeStart":2332,"sourceCodeEnd":2368,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2332-L2368","documentation":"TimeoutException built by checkDeadline when polling for an archive control response exceeds messageTimeoutNs. The client sent the request but no matching response arrived before the deadline; the message includes the correlationId, the configured timeout, and an errorMessage describing which operation timed out.","triggerScenarios":"Any request/response call (startReplay, listRecordings, truncate, etc.) where pollForResponse exhausts ctx.messageTimeoutNs() waiting for the archive's reply on the control response channel.","commonSituations":"Archive overloaded or stuck (e.g. slow catalog, disk issues); request never delivered due to backpressure; control response subscription connected to the wrong stream; very long-running listRecordings over huge catalogs exceeding the default timeout.","solutions":["Increase messageTimeout in AeronArchive.Context (e.g. ctx.messageTimeout(TimeUnit.SECONDS.toNanos(30))).","Verify the control response channel/streamId match the archive's configured response endpoint.","Check archive logs/health for the correlationId to see if the request was processed.","Retry the operation on a new archive session if the archive was restarted mid-request."],"exampleFix":"// before\nAeronArchive.connect(new AeronArchive.Context());\n// after\nAeronArchive.connect(new AeronArchive.Context()\n    .messageTimeout(TimeUnit.SECONDS.toNanos(30)));","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    archive.listRecording(recordingId);\n} catch (TimeoutException e) {\n    // retry with larger timeout or check archive health\n    ctx.messageTimeout(TimeUnit.SECONDS.toNanos(60));\n}","preventionTips":["Set a messageTimeout appropriate for the largest expected operation (e.g. listRecordings on big catalogs).","Monitor archive latency and GC pauses.","Verify control response channel/stream configuration at connect time."],"tags":["aeron-archive","timeout","request-response"],"backgroundTag":"request-timeout","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}