{"record":{"id":"1169620b5deeea4e","repo":"aeron-io/aeron","slug":"failed-to-start-service-ctx-serviceid-leadershiptermid","errorCode":null,"errorMessage":"failed to start service=<ctx.serviceId()> leadershipTermId=<leadershipTermId> logPosition=<logPosition> clusterTime=<clusterTime> snapshotRecordingId=<snapshotRecordingId>","messagePattern":"failed to start service=<ctx\\.serviceId\\(\\)> leadershipTermId=<leadershipTermId> logPosition=<logPosition> clusterTime=<clusterTime> snapshotRecordingId=<snapshotRecordingId>","errorType":"exception","errorClass":"AgentTerminationException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java","lineNumber":812,"sourceCode":"        {\n            activeLifecycleCallback = LIFECYCLE_CALLBACK_NONE;\n        }\n\n        final long id = ackId++;\n        final long relevantId = (null == exception) ? aeron.clientId() : NULL_VALUE;\n        while (!consensusModuleProxy.ack(logPosition, clusterTime, id, relevantId, serviceId))\n        {\n            idle();\n        }\n\n        if (null != exception)\n        {\n            final String message = \"failed to start service=\" + ctx.serviceId() +\n                \" leadershipTermId=\" + leadershipTermId +\n                \" logPosition=\" + logPosition +\n                \" clusterTime=\" + clusterTime +\n                \" snapshotRecordingId=\" + snapshotRecordingId;\n            throw new AgentTerminationException(message, exception);\n        }\n    }\n\n    private int awaitRecoveryCounter(final CountersReader counters)\n    {\n        idleStrategy.reset();\n        int counterId = RecoveryState.findCounterId(counters, ctx.clusterId());\n        while (NULL_COUNTER_ID == counterId)\n        {\n            idle();\n            counterId = RecoveryState.findCounterId(counters, ctx.clusterId());\n        }\n\n        return counterId;\n    }\n\n    private void closeLog()\n    {","sourceCodeStart":794,"sourceCodeEnd":830,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java#L794-L830","documentation":"Thrown as AgentTerminationException when a recovered service fails to start (onStart or onLoadSnapshot threw) during recovery, after loading a snapshot with the given leadershipTermId/logPosition/snapshotRecordingId. The library wraps the underlying exception because a service that cannot start cannot participate in the cluster; the container cannot make progress.","triggerScenarios":"ClusteredService.onStart() or onLoadSnapshot(SnapshotTaker/InputStream) throws during service container recovery after a snapshot restore; service constructor fails; snapshot bytes are corrupt or written by an incompatible service version.","commonSituations":"Deploying a new service jar whose onStart deserializes state incompatible with an old snapshot; corrupted or truncated snapshot recording in the archive; service throwing NPE on restored state; rolling upgrade where snapshot app version differs.","solutions":["Fix the root exception reported as the cause of AgentTerminationException in the service's onStart/onLoadSnapshot","Make the service's onLoadSnapshot/onStart defensive against missing or old-format state","Recover from an earlier good snapshot or take a fresh one by restarting from an empty log if data loss is acceptable","Verify the service class name/instance configuration (aeron.cluster.service.class.name) matches the code that wrote the snapshot"],"exampleFix":"// before\npublic void onLoadSnapshot(InputStream in) {\n    state = deserialize(in); // throws on old format\n}\n// after\npublic void onLoadSnapshot(InputStream in) {\n    try {\n        state = deserialize(in);\n    } catch (Exception ex) {\n        throw new RuntimeException(\"snapshot load failed\", ex);\n    }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { service.onLoadSnapshot(in); service.onStart(session); }\ncatch (AgentTerminationException ex) {\n    log(\"service failed to start from snapshot\", ex.getCause());\n    // fall back to earlier snapshot or halt node for operator intervention\n}","preventionTips":["Make onLoadSnapshot/onStart tolerant of older snapshot formats and null state","Test snapshot restore in CI after every state-model change","Take a fresh snapshot before deploying new service versions","Never throw from onStart on recoverable state issues; repair instead"],"tags":["aeron","cluster","recovery","snapshot"],"backgroundTag":"module-init-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}