apache/seatunnel · error · IllegalArgumentException

Template must contain ${database} and ${table} variables

Error message

Template must contain ${database} and ${table} variables

What it means

IllegalArgumentException thrown by HiveTableTemplateUtils.validateTemplate when the template lacks the required ${database} and/or ${table} placeholder variables. These placeholders are substituted at runtime to build the fully qualified table name in the generated CREATE TABLE SQL.

Source

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

        }

        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(
                        patternStr, java.util.regex.Pattern.CASE_INSENSITIVE);
        java.util.regex.Matcher matcher = pattern.matcher(template);
        if (matcher.find()) {
            String raw = matcher.group(1);
            String defaultLocation = getDefaultTableLocation(database, table);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add both ${database} and ${table} placeholders to the template
2. Escape/protect ${...} if your config layer performs its own variable substitution
3. Compare against the built-in default template and restore missing placeholders
4. Run validateTemplate during startup to catch this before job execution

Example fix

// before
hive.table-create-template = "CREATE TABLE my_db.my_table (id int)"
// after
hive.table-create-template = "CREATE TABLE ${database}.${table} (id int)"

if (!template.contains("${database}") || !template.contains("${table}")) { throw new IllegalArgumentException("template must contain ${database} and ${table}"); }

boolean hasPlaceholders = template != null && template.contains("${database}") && template.contains("${table}");

try { validateTemplate(template); } catch (IllegalArgumentException e) { /* add ${database}/${table} placeholders */ }

When it happens

Trigger: Template hardcodes a table name instead of using ${database}/${table}; typos like {database} or $database without braces; template that only contains CREATE TABLE but no variables.

Common situations: Users writing a fixed table name in a copied DDL; brace-stripping by config templating systems (e.g. envsubst, HOCON substitution consuming ${...}); editing the default template and deleting placeholders.

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

• Template cannot be null or empty
• Template must contain CREATE TABLE statement
• Can't find column in table.
• CREATE_HIVE_TABLE_FAILED
• ILLEGAL_ARGUMENT

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