{"record":{"id":"14663cd5213c080a","repo":"apache/seatunnel","slug":"common-illegal-argument-14663c","errorCode":"COMMON_ILLEGAL_ARGUMENT","errorMessage":"file_name_expression must contains <TRANSACTION_EXPRESSION> when is_enable_transaction is true","messagePattern":"file_name_expression must contains <TRANSACTION_EXPRESSION> when is_enable_transaction is true","errorType":"error_code","errorClass":"FileConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/config/FileSinkConfig.java","lineNumber":137,"sourceCode":"        if (pluginConfig.getOptional(FileBaseSinkOptions.PARTITION_DIR_EXPRESSION).isPresent()\n                && !StringUtils.isBlank(\n                        pluginConfig.get(FileBaseSinkOptions.PARTITION_DIR_EXPRESSION))) {\n            this.partitionDirExpression =\n                    pluginConfig.get(FileBaseSinkOptions.PARTITION_DIR_EXPRESSION);\n        }\n\n        this.isPartitionFieldWriteInFile =\n                pluginConfig.get(FileBaseSinkOptions.IS_PARTITION_FIELD_WRITE_IN_FILE);\n\n        this.tmpPath = pluginConfig.get(FileBaseSinkOptions.TMP_PATH);\n\n        this.fileNameTimeFormat = pluginConfig.get(FileBaseSinkOptions.FILENAME_TIME_FORMAT);\n        this.isEnableTransaction = pluginConfig.get(FileBaseSinkOptions.IS_ENABLE_TRANSACTION);\n        this.encoding = pluginConfig.get(FileBaseSinkOptions.ENCODING);\n\n        if (this.isEnableTransaction\n                && !this.fileNameExpression.contains(FileBaseSinkOptions.TRANSACTION_EXPRESSION)) {\n            throw new FileConnectorException(\n                    CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,\n                    \"file_name_expression must contains \"\n                            + FileBaseSinkOptions.TRANSACTION_EXPRESSION\n                            + \" when is_enable_transaction is true\");\n        }\n\n        // check partition field must in seaTunnelRowTypeInfo\n        if (!CollectionUtils.isEmpty(this.partitionFieldList)\n                && (CollectionUtils.isEmpty(this.sinkColumnList)\n                        || !new HashSet<>(this.sinkColumnList)\n                                .containsAll(this.partitionFieldList))) {\n            throw new FileConnectorException(\n                    CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,\n                    \"partition fields must in sink columns\");\n        }\n\n        if (!CollectionUtils.isEmpty(this.partitionFieldList) && !isPartitionFieldWriteInFile) {\n            if (!this.sinkColumnList.removeAll(this.partitionFieldList)) {","sourceCodeStart":119,"sourceCodeEnd":155,"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/config/FileSinkConfig.java#L119-L155","documentation":"FileSinkConfig's constructor validates that when is_enable_transaction is true, the file_name_expression must contain the <TRANSACTION_EXPRESSION> placeholder. Transaction mode needs a unique suffix per attempt so uncommitted/aborted files can be distinguished and cleaned up. Throws FileConnectorException with CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT.","triggerScenarios":"is_enable_transaction = true while file_name_expression is unset or set without '<TRANSACTION_EXPRESSION>' (e.g. 'out_${now}').","commonSituations":"Users enabling transactional writes for exactly-once semantics but writing a custom filename that drops the placeholder; templates copied from non-transactional examples.","solutions":["Add the placeholder: file_name_expression = \"out_<TRANSACTION_EXPRESSION>\".","Or set is_enable_transaction = false if exactly-once file commit is not needed.","Use the default file_name_expression, which already contains the transaction expression."],"exampleFix":"// before\nfile_name_expression = \"data_${now}\"\nis_enable_transaction = true\n// after\nfile_name_expression = \"data_${now}_<TRANSACTION_EXPRESSION>\"\nis_enable_transaction = true","handlingStrategy":"validation","validationCode":"if (config.isEnableTransaction && (config.fileNameExpression == null || !config.fileNameExpression.contains(\"<TRANSACTION_EXPRESSION>\"))) {\n  throw new IllegalArgumentException(\"file_name_expression must contain <TRANSACTION_EXPRESSION> when is_enable_transaction=true\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  sink.open();\n} catch (FileConnectorException e) {\n  if (e.getHttpCodeOrCode() == CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT) {\n    // fix file_name_expression and resubmit\n  }\n  throw e;\n}","preventionTips":["Use file_name_expression templates that always include <TRANSACTION_EXPRESSION> when transactions are on.","Keep transaction and filename options in the same config block to review together.","Catch FileConnectorException at job submission to fail fast with a clear message."],"tags":["file-sink","transaction","filename-template"],"backgroundTag":"missing-required-argument","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}