apache/seatunnel · error · IllegalArgumentException

Template cannot be null or empty

Error message

Template cannot be null or empty

What it means

IllegalArgumentException thrown by HiveTableTemplateUtils.validateTemplate when the supplied create-table template is null or only whitespace. The template is the user-provided DDL used to create Hive tables, so an empty one can never produce valid SQL.

Source

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

                java.util.regex.Pattern.compile(
                        partitionPattern, java.util.regex.Pattern.CASE_INSENSITIVE);
        java.util.regex.Matcher matcher = pattern.matcher(template);

        if (matcher.find()) {
            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) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Provide a valid DDL template containing a CREATE TABLE statement
2. Check the config key/file that supplies the template is non-empty
3. Trim-inspect the template string before invoking the catalog operation
4. Add a startup validation of the template in the source/sink factory

Example fix

// before
String template = config.get(TEMPLATE_OPTION); // may be empty
// after
String template = config.get(TEMPLATE_OPTION);
if (template == null || template.trim().isEmpty()) {
    throw new IllegalArgumentException("hive.table-create-template must be set");
}

if (template == null || template.trim().isEmpty()) { template = DEFAULT_HIVE_TEMPLATE; }

boolean templatePresent = template != null && !template.trim().isEmpty();

try { validateTemplate(template); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Provide hive.table-create-template: " + e.getMessage()); }

When it happens

Trigger: Calling validateTemplate(null) or validateTemplate(" "); passing an empty template option from config or reading an empty template file/string in buildCreateTableSQL flows.

Common situations: Template option left empty in job config; template loaded from a file that exists but is empty; string substitution (env var, placeholder) resolving to blank.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Table format cannot be null or empty
• Template must contain CREATE TABLE statement
• Template must contain ${database} and ${table} variables
• Condition operator must not be null
• Invalid metalake table id:

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