{"record":{"id":"9f6d5a52ea4e953d","repo":"apache/seatunnel","slug":"failed-to-load-readytoclosestartingtask-from-imap","errorCode":null,"errorMessage":"Failed to load readyToCloseStartingTask from IMap, key: %s","messagePattern":"Failed to load readyToCloseStartingTask from IMap, key: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/checkpoint/CheckpointCoordinator.java","lineNumber":579,"sourceCode":"        try {\n            Object stored = runningJobStateIMap.get(readyToCloseImapKey);\n            if (stored instanceof Set) {\n                Set<TaskLocation> result = (Set<TaskLocation>) stored;\n                LOG.info(\n                        \"Loaded readyToCloseStartingTask from IMap, job id: {}, pipeline id: {}, value: {}\",\n                        jobId,\n                        pipelineId,\n                        result);\n                return result;\n            }\n            return null;\n        } catch (Exception e) {\n            LOG.error(\n                    \"Failed to load readyToCloseStartingTask from IMap, job id: {}, pipeline id: {}.\",\n                    jobId,\n                    pipelineId,\n                    e);\n            throw new RuntimeException(\n                    \"Failed to load readyToCloseStartingTask from IMap, key: \"\n                            + readyToCloseImapKey,\n                    e);\n        }\n    }\n\n    private void updateReadyToCloseStartingTask() {\n        try {\n            RetryUtils.retryWithException(\n                    () -> {\n                        runningJobStateIMap.compute(\n                                readyToCloseImapKey,\n                                (k, exist) -> {\n                                    Set<TaskLocation> merged =\n                                            exist instanceof Set\n                                                    ? new HashSet<>((Set<TaskLocation>) exist)\n                                                    : new HashSet<>();\n                                    merged.addAll(readyToCloseStartingTask);","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/checkpoint/CheckpointCoordinator.java#L561-L597","documentation":"CheckpointCoordinator.loadReadyToCloseStartingTask reads the readyToCloseStartingTask marker from the distributed IMap; if any exception occurs while loading, it logs the job/pipeline IDs and rethrows a RuntimeException wrapping the cause. This marker records whether the starting (source) task is ready to close, and failing to load it means the coordinator cannot safely continue the checkpoint/close protocol.","triggerScenarios":"IMap read failure during restoredReadyToClose: Hazelcast operation timeout, partition migration/failover while reading, deserialization failure of the stored value, or cluster connection loss during the get() call.","commonSituations":"Network instability between master node and Hazelcast cluster during job restore; master failover mid-checkpoint; corrupted or incompatible serialized state after a SeaTunnel version upgrade.","solutions":["Inspect the wrapped cause (getCause()) — fix the underlying Hazelcast/IMap issue (timeouts, connectivity) it reports","Retry the job restore; transient Hazelcast timeouts and migration pauses usually resolve on re-run","Check cluster stability and Hazelcast logs for partition migration or split-brain around the failure time","If it follows a version upgrade, verify checkpoint/state storage format compatibility between old and new versions","Ensure IMap persistence/backup config is consistent so the key exists after failover"],"exampleFix":"// before\ntry {\n    loadReadyToCloseStartingTask();\n} catch (Exception e) {\n    // swallowed or generic handling\n}\n\n// after\ntry {\n    loadReadyToCloseStartingTask();\n} catch (RuntimeException e) {\n    LOG.error(\"readyToClose load failed, key={}\", readyToCloseImapKey, e.getCause());\n    throw e; // fail job; retry on resubmit after fixing IMap/cluster issue\n}","handlingStrategy":"retry","validationCode":"// pre-check key presence\nboolean present = hazelcastInstance.getMap(mapName).containsKey(readyToCloseImapKey);","typeGuard":null,"tryCatchPattern":"try {\n    loadReadyToCloseStartingTask();\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof HazelcastInstanceNotActiveException || e.getCause() instanceof OperationTimeoutException) {\n        retryWithBackoff();\n    } else { throw e; }\n}","preventionTips":["Keep Hazelcast operation timeouts generous on large clusters","Monitor cluster health/partition migration around job restore","Verify state-format compatibility across upgrades"],"tags":["zeta-engine","checkpoint","imap","hazelcast","failover"],"backgroundTag":"database-query-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}