{"record":{"id":"aac4a1440a6e7341","repo":"apache/seatunnel","slug":"single-file-mode-is-not-supported-when-checkpoint-aac4a1","errorCode":null,"errorMessage":"Single file mode is not supported when checkpoint is enabled or in streaming mode.","messagePattern":"Single file mode is not supported when checkpoint is enabled or in streaming mode\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/BaseMultipleTableFileSink.java","lineNumber":86,"sourceCode":"    private String jobId;\n    private JobContext jobContext;\n    private final ReadonlyConfig readonlyConfig;\n\n    public abstract String getPluginName();\n\n    public BaseMultipleTableFileSink(\n            HadoopConf hadoopConf, ReadonlyConfig readonlyConfig, CatalogTable catalogTable) {\n        this.readonlyConfig = readonlyConfig;\n        this.hadoopConf = hadoopConf;\n        this.fileSinkConfig =\n                new FileSinkConfig(readonlyConfig, catalogTable.getSeaTunnelRowType());\n        this.catalogTable = catalogTable;\n    }\n\n    public void preCheckConfig() {\n        if (readonlyConfig.get(FileBaseSinkOptions.SINGLE_FILE_MODE)\n                && jobContext.isEnableCheckpoint()) {\n            throw new IllegalArgumentException(\n                    \"Single file mode is not supported when checkpoint is enabled or in streaming mode.\");\n        }\n    }\n\n    @Override\n    public void setJobContext(JobContext jobContext) {\n        this.jobContext = jobContext;\n        preCheckConfig();\n    }\n\n    @Override\n    public SinkWriter<SeaTunnelRow, FileCommitInfo, FileSinkState> restoreWriter(\n            SinkWriter.Context context, List<FileSinkState> states) {\n        return new BaseFileSinkWriter(\n                createWriteStrategy(), hadoopConf, context, jobContext.getJobId(), states);\n    }\n\n    @Override","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/BaseMultipleTableFileSink.java#L68-L104","documentation":"BaseMultipleTableFileSink.preCheckConfig rejects single_file_mode=true when checkpointing is enabled (or the job runs in streaming mode, which implies checkpoint). Single-file mode relies on finalizing exactly one file at job end, which is unsafe with checkpoints/restarts because partial files could be duplicated or never committed. The check runs in setJobContext during sink initialization.","triggerScenarios":"Configuring single_file_mode=true in a streaming SeaTunnel job, or a batch job with checkpoint enabled, then initializing the sink.","commonSituations":"Streaming CDC-to-file jobs with single_file_mode=true; batch jobs that accidentally enable checkpoint; users migrating batch configs to streaming without changing file options.","solutions":["Set single_file_mode = false and rely on per-subtask files.","Run the job in batch mode with checkpoint disabled.","If single consolidated output is required, use batch mode and post-merge files with a script or dedicated filesystem move."],"exampleFix":"// before\nsink {\n  Console {\n    source_table_name = \"cdc\"\n  }\n  Fake {\n    single_file_mode = true\n  }\n}\n// after\nsink {\n  Fake {\n    single_file_mode = false\n  }\n}","handlingStrategy":"validation","validationCode":"if (config.singleFileMode && (jobMode == JobMode.STREAMING || checkpointEnabled)) {\n  throw new IllegalArgumentException(\"single_file_mode requires batch mode with checkpoint disabled\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat single_file_mode as batch-only; document it in job templates.","Check job mode/checkpoint flags in CI before deploying streaming configs.","Prefer per-subtask files plus a post-job merge for consolidated output."],"tags":["file-sink","checkpoint","streaming"],"backgroundTag":"conflicting-config-options","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"}