apache/seatunnel · error · IllegalArgumentException

Template must contain CREATE TABLE statement

Error message

Template must contain CREATE TABLE statement

What it means

IllegalArgumentException thrown by HiveTableTemplateUtils.validateTemplate when the template does not contain the required "CREATE TABLE" statement (case-insensitive check). The template must be a full DDL that creates a Hive table.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveTableTemplateUtils.java:159

            String partitionClause = matcher.group(1);
            // Extract field names (basic parsing)
            return java.util.Arrays.stream(partitionClause.split(","))
                    .map(field -> field.trim().split("\\s+")[0].replaceAll("`", ""))
                    .collect(Collectors.toList());
        }

        return java.util.Collections.emptyList();
    }

    /** Validate template syntax (basic validation) */
    public static void validateTemplate(String template) {
        if (template == null || template.trim().isEmpty()) {
            throw new IllegalArgumentException("Template cannot be null or empty");
        }

        // Check for required CREATE TABLE statement
        if (!template.toUpperCase().contains("CREATE TABLE")) {
            throw new IllegalArgumentException("Template must contain CREATE TABLE statement");
        }

        // Check for required variables
        if (!template.contains("${database}") || !template.contains("${table}")) {
            throw new IllegalArgumentException(
                    "Template must contain ${database} and ${table} variables");
        }
    }

    /** Extract LOCATION path from template. If it contains ${table_location}, replace it. */
    public static String extractLocationFromTemplate(
            String template, String database, String table) {
        if (template == null) {
            return null;
        }
        String patternStr = "LOCATION\\s+'([^']+)'";
        java.util.regex.Pattern pattern =
                java.util.regex.Pattern.compile(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Ensure the template is a complete DDL starting with CREATE TABLE (EXTERNAL allowed)
2. Verify the template survived config parsing intact (quotes/escaping)
3. Use the built-in default template as a starting point and modify columns/LOCATION
4. Call validateTemplate(template) during config parsing to fail early with this clear message

Example fix

// before
hive.table-create-template = "${database}.${table} (id int)"
// after
hive.table-create-template = "CREATE TABLE ${database}.${table} (id int) WITH ('format'='json')"

if (!template.toUpperCase().contains("CREATE TABLE")) { throw new IllegalArgumentException("template must be a CREATE TABLE DDL"); }

boolean isCreateTableDdl = template != null && template.toUpperCase(Locale.ROOT).contains("CREATE TABLE");

try { validateTemplate(template); } catch (IllegalArgumentException e) { /* fix template to include CREATE TABLE */ }

When it happens

Trigger: Passing a partial DDL (e.g. only column list or INSERT statement), a SELECT query, or a DDL with different casing/wording like "CREATE EXTERNAL TABLE" is fine but "CREATE VIEW" or missing statement fails.

Common situations: Users copying only the column definitions into the template; using a wrong doc example; template accidentally truncated when embedded in a HOCON config (unescaped quotes/newlines).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Can't find column in table.
• Template cannot be null or empty
• Template must contain ${database} and ${table} variables
• Can't find column ${col} in table.
• Failed EXECUTE SQL in catalog %s

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