{"record":{"id":"a38a60a9e9bcc3ce","repo":"apache/seatunnel","slug":"single-file-mode-is-not-supported-when-checkpoint","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/BaseFileSink.java","lineNumber":70,"sourceCode":"    public BaseFileSink(ReadonlyConfig pluginConfig, CatalogTable catalogTable) {\n        this.pluginConfig = pluginConfig;\n        this.catalogTable = catalogTable;\n        this.fileSinkConfig = new FileSinkConfig(pluginConfig, catalogTable.getSeaTunnelRowType());\n        this.hadoopConf = initHadoopConf();\n    }\n\n    protected abstract HadoopConf initHadoopConf();\n\n    @Override\n    public Optional<CatalogTable> getWriteCatalogTable() {\n        return Optional.of(catalogTable);\n    }\n\n    public void preCheckConfig() {\n        if (pluginConfig.getOptional(FileBaseSinkOptions.SINGLE_FILE_MODE).isPresent()\n                && pluginConfig.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        if (pluginConfig.getOptional(FileBaseSinkOptions.CREATE_EMPTY_FILE_WHEN_NO_DATA).isPresent()\n                && pluginConfig.get(FileBaseSinkOptions.CREATE_EMPTY_FILE_WHEN_NO_DATA)\n                && !fileSinkConfig.getPartitionFieldList().isEmpty()) {\n            throw new IllegalArgumentException(\n                    \"Generate empty file when no data is not supported when partition is enabled.\");\n        }\n    }\n\n    @Override\n    public void setJobContext(JobContext jobContext) {\n        this.jobContext = jobContext;\n        this.jobId = jobContext.getJobId();\n        preCheckConfig();\n    }\n\n    @Override","sourceCodeStart":52,"sourceCodeEnd":88,"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/BaseFileSink.java#L52-L88","documentation":"BaseFileSink.preCheckConfig rejects combining SINGLE_FILE_MODE with checkpoint-enabled (batch-with-checkpoint or streaming) jobs, because single-file output relies on a single writer and cannot be reconciled with checkpointed, possibly rescaled sinks.","triggerScenarios":"Configuring single_file_mode = true on any file sink while running in streaming mode or with checkpoint enabled (e.g. checkpoint_interval set, or -e run in streaming), causing preCheckConfig (invoked from setJobContext) to throw.","commonSituations":"Users want one merged output file in a streaming job; enabling checkpoint for exactly-once while keeping single_file_mode from a batch template; job mode switched from batch to streaming without revisiting sink options.","solutions":["Disable single_file_mode and instead set a parallelism of 1 for the sink to get a single output file","Run the job in batch mode with checkpoint disabled if single-file output is essential","Merge output files in a post-processing step after the job finishes"],"exampleFix":"// before\nsink {\n  LocalFile {\n    single_file_mode = true\n  }\n}\n// streaming job\n// after\nsink {\n  LocalFile {\n    parallelism = 1\n  }\n}","handlingStrategy":"validation","validationCode":"if (config.get(\"single_file_mode\") == true && (jobMode == STREAMING || checkpointEnabled)) {\n    throw new IllegalArgumentException(\"single_file_mode requires batch mode with checkpoint disabled\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use sink parallelism = 1 instead of single_file_mode in streaming jobs","Revisit sink options when switching a job between batch and streaming modes"],"tags":["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-14T05:17:10.506Z"}