{"record":{"id":"fba3a1020bf9c9f1","repo":"apache/seatunnel","slug":"failed-to-close-auxiliary-state-store","errorCode":null,"errorMessage":"Failed to close auxiliary state store","messagePattern":"Failed to close auxiliary state store","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/common/statestore/DefaultAuxiliaryStateStores.java","lineNumber":63,"sourceCode":"    @Override\n    public CheckpointOverviewStateStore checkpointOverviewStateStore() {\n        return checkpointOverviewStateStore;\n    }\n\n    @Override\n    public void close() {\n        closeIfPossible(checkpointOverviewStateStore);\n        closeIfPossible(metricsSnapshotStore);\n    }\n\n    private void closeIfPossible(Object store) {\n        if (!(store instanceof AutoCloseable)) {\n            return;\n        }\n        try {\n            ((AutoCloseable) store).close();\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Failed to close auxiliary state store\", e);\n        }\n    }\n}\n","sourceCodeStart":45,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/common/statestore/DefaultAuxiliaryStateStores.java#L45-L67","documentation":"DefaultAuxiliaryStateStores.closeIfPossible closes an auxiliary state store via AutoCloseable.close(); if close() throws any Exception it wraps it in an IllegalStateException with the message 'Failed to close auxiliary state store'. This surfaces resource-cleanup failures (e.g., releasing file/network handles in the state store) instead of silently swallowing them.","triggerScenarios":"Calling close() on a DefaultAuxiliaryStateStores whose underlying store's AutoCloseable.close() throws — I/O errors while flushing/closing local state files, locked files, or network state-store clients failing to disconnect.","commonSituations":"State directory on a full/unmounted disk or NFS hang at shutdown; file handles still held by another process on Windows; state store backend (e.g., local file or object storage client) network failure during engine shutdown or job cleanup.","solutions":["Inspect the wrapped cause (getCause()) — it contains the actual close failure (IOException, etc.) from the underlying store","Check disk space, mounts, and file permissions for the state store directory","Ensure no other process holds the state files open (especially on Windows) before engine shutdown","Retry engine shutdown once the underlying storage is reachable; close failures are often transient storage issues","If a custom AuxiliaryStateStore is in use, make its close() idempotent and avoid throwing on already-closed resources"],"exampleFix":"// before\n// custom store\npublic void close() throws Exception {\n    outStream.flush(); // throws if disk full/handle closed\n}\n\n// after\n@Override\npublic void close() throws Exception {\n    try {\n        outStream.flush();\n    } finally {\n        outStream.close();\n    }\n}","handlingStrategy":"try-catch","validationCode":"// pre-shutdown sanity: state dir writable and has free space\nFiles.isWritable(stateDir);\nlong usable = Files.getFileStore(stateDir).getUsableSpace();","typeGuard":null,"tryCatchPattern":"try {\n    auxiliaryStateStores.close();\n} catch (IllegalStateException e) {\n    LOG.error(\"Auxiliary state store close failed: {}\", e.getCause(), e);\n}","preventionTips":["Keep state directories on reliable local disks with free space","Make custom stores' close() idempotent and quiet on double-close","Avoid holding state files in other processes during shutdown"],"tags":["zeta-engine","state-store","resource-cleanup","io"],"backgroundTag":"file-close-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}