{"record":{"id":"fe4785ee70d9cb71","repo":"apache/seatunnel","slug":"single-file-mode-is-not-supported-when-file-name-e","errorCode":null,"errorMessage":"Single file mode is not supported when file_name_expression not contains <DEFAULT_FILE_NAME_EXPRESSION> but has parallel subtasks.","messagePattern":"Single file mode is not supported when file_name_expression not contains <DEFAULT_FILE_NAME_EXPRESSION> but has parallel subtasks\\.","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/BaseFileSinkWriter.java","lineNumber":128,"sourceCode":"                        writeStrategy.getFileSinkConfig().getFileNameExpression())) {\n            throw new IllegalArgumentException(\n                    \"Binary custom filename requires a unique filename expression when parallel \"\n                            + \"subtasks are used. Please include \"\n                            + DEFAULT_FILE_NAME_EXPRESSION\n                            + \" or ${\"\n                            + Constants.UUID\n                            + \"} in \"\n                            + FILE_NAME_EXPRESSION.key()\n                            + \".\");\n        }\n        if (writeStrategy.getFileSinkConfig().isSingleFileMode()\n                && context.getNumberOfParallelSubtasks() > 1) {\n            if (StringUtils.isNotEmpty(writeStrategy.getFileSinkConfig().getFileNameExpression())\n                    && !writeStrategy\n                            .getFileSinkConfig()\n                            .getFileNameExpression()\n                            .contains(DEFAULT_FILE_NAME_EXPRESSION)) {\n                throw new IllegalArgumentException(\n                        \"Single file mode is not supported when \"\n                                + FILE_NAME_EXPRESSION.key()\n                                + \" not contains \"\n                                + DEFAULT_FILE_NAME_EXPRESSION\n                                + \" but has parallel subtasks.\");\n            }\n        }\n    }\n\n    private boolean hasParallelUniqueFilenameExpression(String fileNameExpression) {\n        return StringUtils.isBlank(fileNameExpression)\n                || fileNameExpression.contains(DEFAULT_FILE_NAME_EXPRESSION)\n                || fileNameExpression.contains(\"${\" + Constants.UUID + \"}\");\n    }\n\n    private List<String> findTransactionList(\n            String jobId, String uuidPrefix, HadoopFileSystemProxy hadoopFileSystemProxy)\n            throws IOException {","sourceCodeStart":110,"sourceCodeEnd":146,"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/BaseFileSinkWriter.java#L110-L146","documentation":"BaseFileSinkWriter validates at startup that single-file mode (writing all subtasks into one file) cannot be combined with parallel subtasks when file_name_expression is set but does not contain the placeholder that makes each subtask's filename unique. Without the placeholder, parallel subtasks would collide writing the same file. This is a fail-fast IllegalArgumentException thrown during sink configuration pre-check.","triggerScenarios":"Creating a file sink with parallelism > 1, single_file_mode=true, a non-empty file_name_expression that lacks the <DEFAULT_FILE_NAME_EXPRESSION> (or format-specific) placeholder token.","commonSituations":"Users set a custom file_name_expression like 'data_${date}' for parallel batch jobs; multi-thread/multi-node writes with custom names; copy-pasting single-machine configs into a cluster job.","solutions":["Include the placeholder in file_name_expression, e.g. 'data_${date}_<DEFAULT_FILE_NAME_EXPRESSION>' or set sink.parallelism=1.","Set file_name_expression to null/omit it so the default per-subtask naming is used.","If a truly single output file is required, set single_file_mode=false and parallelism=1, or write to a single partition and merge downstream."],"exampleFix":"// before\nsink {\n  FakeSource {\n    parallelism = 4\n    file_name_expression = \"out_${now}\"\n    single_file_mode = true\n  }\n}\n// after\nsink {\n  FakeSource {\n    parallelism = 4\n    file_name_expression = \"out_${now}_<DEFAULT_FILE_NAME_EXPRESSION>\"\n    single_file_mode = true\n  }\n}","handlingStrategy":"validation","validationCode":"if (config.singleFileMode && parallelism > 1 && config.fileNameExpression != null && !config.fileNameExpression.contains(\"<DEFAULT_FILE_NAME_EXPRESSION>\")) {\n  throw new IllegalArgumentException(\"file_name_expression must contain <DEFAULT_FILE_NAME_EXPRESSION> in parallel single-file mode\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include a uniqueness placeholder in custom file_name_expression when parallelism > 1.","Lint SeaTunnel HOCON configs before submission for single_file_mode + parallelism conflicts.","Keep sink parallelism explicit in configs so the conflict is visible."],"tags":["file-sink","parallelism","configuration"],"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"}