apache/seatunnel · error · IllegalArgumentException

Single file mode is not supported when checkpoint is enabled

Error message

Single file mode is not supported when checkpoint is enabled or in streaming mode.

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/BaseMultipleTableFileSink.java:86

    private String jobId;
    private JobContext jobContext;
    private final ReadonlyConfig readonlyConfig;

    public abstract String getPluginName();

    public BaseMultipleTableFileSink(
            HadoopConf hadoopConf, ReadonlyConfig readonlyConfig, CatalogTable catalogTable) {
        this.readonlyConfig = readonlyConfig;
        this.hadoopConf = hadoopConf;
        this.fileSinkConfig =
                new FileSinkConfig(readonlyConfig, catalogTable.getSeaTunnelRowType());
        this.catalogTable = catalogTable;
    }

    public void preCheckConfig() {
        if (readonlyConfig.get(FileBaseSinkOptions.SINGLE_FILE_MODE)
                && jobContext.isEnableCheckpoint()) {
            throw new IllegalArgumentException(
                    "Single file mode is not supported when checkpoint is enabled or in streaming mode.");
        }
    }

    @Override
    public void setJobContext(JobContext jobContext) {
        this.jobContext = jobContext;
        preCheckConfig();
    }

    @Override
    public SinkWriter<SeaTunnelRow, FileCommitInfo, FileSinkState> restoreWriter(
            SinkWriter.Context context, List<FileSinkState> states) {
        return new BaseFileSinkWriter(
                createWriteStrategy(), hadoopConf, context, jobContext.getJobId(), states);
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set single_file_mode = false and rely on per-subtask files.
2. Run the job in batch mode with checkpoint disabled.
3. If single consolidated output is required, use batch mode and post-merge files with a script or dedicated filesystem move.

Example fix

// before
sink {
  Console {
    source_table_name = "cdc"
  }
  Fake {
    single_file_mode = true
  }
}
// after
sink {
  Fake {
    single_file_mode = false
  }
}

if (config.singleFileMode && (jobMode == JobMode.STREAMING || checkpointEnabled)) {
  throw new IllegalArgumentException("single_file_mode requires batch mode with checkpoint disabled");
}

When it happens

Trigger: Configuring single_file_mode=true in a streaming SeaTunnel job, or a batch job with checkpoint enabled, then initializing the sink.

Common situations: 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.

Related errors

• Single file mode is not supported when checkpoint is enabled
• checkpoint {} do not exist or have already been committed.
• '%s' source don't support off-line job.
• CONFIGURATION_FAILED
• ACKNOWLEDGE_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/aac4a1440a6e7341. Report an issue: GitHub.