apache/seatunnel · error · SeaTunnelException

Table %s field name cannot be empty

Error message

Table %s field name cannot be empty

What it means

Thrown by TableFactoryContext.checkCatalogTableIllegal while validating a CatalogTable's schema: a field name is null, empty, or whitespace-only. The factory context refuses to construct source/sink/transform plugins against a table schema with blank field names because they cannot be referenced, resolved, or mapped downstream.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/factory/TableFactoryContext.java:47

import java.util.List;

@Getter
public abstract class TableFactoryContext {

    private final ReadonlyConfig options;
    private final ClassLoader classLoader;

    public TableFactoryContext(ReadonlyConfig options, ClassLoader classLoader) {
        this.options = options;
        this.classLoader = classLoader;
    }

    protected static void checkCatalogTableIllegal(List<CatalogTable> catalogTables) {
        for (CatalogTable catalogTable : catalogTables) {
            List<String> alreadyChecked = new ArrayList<>();
            for (String fieldName : catalogTable.getTableSchema().getFieldNames()) {
                if (StringUtils.isBlank(fieldName)) {
                    throw new SeaTunnelException(
                            String.format(
                                    "Table %s field name cannot be empty",
                                    catalogTable.getTablePath().getFullName()));
                }
                if (alreadyChecked.contains(fieldName)) {
                    throw new SeaTunnelException(
                            String.format(
                                    "Table %s field %s duplicate",
                                    catalogTable.getTablePath().getFullName(), fieldName));
                }
                alreadyChecked.add(fieldName);
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the table schema at the failing factory and give every field a non-blank name.
  2. Fix the HOCON schema block so every key is a real column name.
  3. If the schema comes from a custom Catalog/connector, fix its column-name derivation before building the CatalogTable.
  4. Validate programmatically with catalogTable.getTableSchema().getFieldNames() before passing to the factory.

Example fix

// before
schema { fields { "" = string, name = string } }
// after
schema { fields { id = string, name = string } }
Defensive patterns

Strategy: validation

Validate before calling

boolean ok = catalogTables.stream().allMatch(t -> Arrays.stream(t.getTableSchema().getFieldNames()).allMatch(n -> n != null && !n.isBlank()));

Type guard

boolean hasBlank = schema.getFieldNames() == null || Arrays.stream(schema.getFieldNames()).anyMatch(n -> n == null || n.isBlank());

Try / catch

try { factory.createAndPrepareSource(...) } catch (SeaTunnelException e) { if (e.getMessage().contains("field name cannot be empty")) { log.error("schema has blank field names"); } throw e; }

Prevention

When it happens

Trigger: Calling TableFactoryContext (or createAndPrepareSource/Sink/Transform paths) with a CatalogTable whose TableSchema contains a blank field name — typically produced by a catalog that mis-declares columns, or by user-supplied schema/Transform definitions like 'schema { fields { "" = string } }' or ' '.

Common situations: Hand-written schema blocks in HOCON with an empty key or stray whitespace; custom Catalog building code that adds columns without names; a connector's catalog implementation deriving field names from upstream metadata that contains blanks.

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

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