{"record":{"id":"0229fa7e01d46d86","repo":"apache/seatunnel","slug":"common-24","errorCode":"COMMON-24","errorMessage":"The table of <tableName> has no <keyName>, but the template \n <template> \n which has the place holder named <placeholder>. Please use the option named <optionName> to specify sql template","messagePattern":"The table of <tableName> has no <keyName>, but the template \n <template> \n which has the place holder named <placeholder>\\. Please use the option named <optionName> to specify sql template","errorType":"error_code","errorClass":"SeaTunnelRuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-common/src/main/java/org/apache/seatunnel/connectors/seatunnel/common/sql/template/SqlTemplate.java","lineNumber":33,"sourceCode":" * limitations under the License.\n */\n\npackage org.apache.seatunnel.connectors.seatunnel.common.sql.template;\n\nimport org.apache.seatunnel.shade.org.apache.commons.lang3.StringUtils;\n\nimport org.apache.seatunnel.api.sink.SaveModePlaceHolder;\nimport org.apache.seatunnel.common.exception.CommonError;\n\npublic class SqlTemplate {\n    public static void canHandledByTemplateWithPlaceholder(\n            String createTemplate,\n            String placeholder,\n            String actualPlaceHolderValue,\n            String tableName,\n            String optionsKey) {\n        if (createTemplate.contains(placeholder) && StringUtils.isBlank(actualPlaceHolderValue)) {\n            throw CommonError.sqlTemplateHandledError(\n                    tableName,\n                    SaveModePlaceHolder.getDisplay(placeholder),\n                    createTemplate,\n                    placeholder,\n                    optionsKey);\n        }\n    }\n}\n","sourceCodeStart":15,"sourceCodeEnd":42,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-common/src/main/java/org/apache/seatunnel/connectors/seatunnel/common/sql/template/SqlTemplate.java#L15-L42","documentation":"Thrown when a SQL create-template option contains a placeholder (e.g. {{table_name}}) but the value for that placeholder (such as the actual table name) was not provided via the corresponding option. SeaTunnel's SqlTemplate cannot build a valid SQL statement without it, so it fails fast with guidance pointing at the option that must be set.","triggerScenarios":"Calling canHandledByTemplateWithPlaceholder (via save-mode template handling) when createTemplate.contains(placeholder) is true but actualPlaceHolderValue is null or blank.","commonSituations":"User configures save_mode with a template like 'CREATE TABLE {{table_name}} (...)' but forgets to set the schema_save_mode-related option (e.g. table_name or the create-template data table option); copying a config between jobs where table identifiers were env-specific.","solutions":["Set the option named in the error message (optionsKey) so the placeholder has a non-blank value","Remove the placeholder from the template if you intend a static SQL template","Verify save_mode template config keys match the connector's documented option names"],"exampleFix":"# before\nsave_mode {\n  create_template = \"CREATE TABLE {{table_name}} (...)\"\n}\n# after\nsave_mode {\n  create_template = \"CREATE TABLE {{table_name}} (...)\"\n  table_name = \"my_target_table\"\n}","handlingStrategy":"validation","validationCode":"if (createTemplate.contains(\"{{table_name}}\") && (tableName == null || tableName.isBlank())) { throw new IllegalArgumentException(\"table_name option required for template\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set the placeholder-matching option when using a save_mode template with placeholders","Grep your config for '{{' placeholders and verify each has a corresponding option","Keep template configs copied between jobs consistent by templating values externally"],"tags":["sql","config","template","placeholder"],"backgroundTag":"missing-required-config-field","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"}