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.

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

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

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

Appendix: 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)