apache/seatunnel · error · SeaTunnelRuntimeException

COMMON-24

COMMON-24

Error message

The table of <tableName> has no <keyName>, but the template 
 <template> 
 which has the place holder named <placeholder>. Please use the option named <optionName> to specify sql template

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-common/src/main/java/org/apache/seatunnel/connectors/seatunnel/common/sql/template/SqlTemplate.java:33

 * limitations under the License.
 */

package org.apache.seatunnel.connectors.seatunnel.common.sql.template;

import org.apache.seatunnel.shade.org.apache.commons.lang3.StringUtils;

import org.apache.seatunnel.api.sink.SaveModePlaceHolder;
import org.apache.seatunnel.common.exception.CommonError;

public class SqlTemplate {
    public static void canHandledByTemplateWithPlaceholder(
            String createTemplate,
            String placeholder,
            String actualPlaceHolderValue,
            String tableName,
            String optionsKey) {
        if (createTemplate.contains(placeholder) && StringUtils.isBlank(actualPlaceHolderValue)) {
            throw CommonError.sqlTemplateHandledError(
                    tableName,
                    SaveModePlaceHolder.getDisplay(placeholder),
                    createTemplate,
                    placeholder,
                    optionsKey);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set the option named in the error message (optionsKey) so the placeholder has a non-blank value
2. Remove the placeholder from the template if you intend a static SQL template
3. Verify save_mode template config keys match the connector's documented option names

Example fix

# before
save_mode {
  create_template = "CREATE TABLE {{table_name}} (...)"
}
# after
save_mode {
  create_template = "CREATE TABLE {{table_name}} (...)"
  table_name = "my_target_table"
}

if (createTemplate.contains("{{table_name}}") && (tableName == null || tableName.isBlank())) { throw new IllegalArgumentException("table_name option required for template"); }

When it happens

Trigger: Calling canHandledByTemplateWithPlaceholder (via save-mode template handling) when createTemplate.contains(placeholder) is true but actualPlaceHolderValue is null or blank.

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

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• The source table[%s] is not found
• SQL_OPERATION_FAILED
• ILLEGAL_ARGUMENT
• CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT
• oracle_insert_mode=APPEND_VALUES only supports generated INS

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