apache/seatunnel · error · SeaTunnelException

Schema config can not be empty

Error message

Schema config can not be empty

What it means

CatalogTableUtil.getCatalogTables treats an explicitly present but empty 'schema' config block as invalid. If the user wrote a schema key with no fields, the utility cannot build a meaningful CatalogTable, so it throws SeaTunnelException.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/catalog/CatalogTableUtil.java:107

     */
    @Deprecated
    public static List<CatalogTable> getCatalogTables(
            ReadonlyConfig readonlyConfig, ClassLoader classLoader) {

        // We use plugin_name as factoryId, so MySQL-CDC should be MySQL
        String factoryId =
                readonlyConfig.get(ConnectorCommonOptions.PLUGIN_NAME).replace("-CDC", "");
        return getCatalogTables(factoryId, readonlyConfig, classLoader);
    }

    @Deprecated
    public static List<CatalogTable> getCatalogTables(
            String factoryId, ReadonlyConfig readonlyConfig, ClassLoader classLoader) {
        // Highest priority: specified schema
        Map<String, Object> schemaMap = readonlyConfig.get(ConnectorCommonOptions.SCHEMA);
        if (schemaMap != null) {
            if (schemaMap.isEmpty()) {
                throw new SeaTunnelException("Schema config can not be empty");
            }
            CatalogTable catalogTable = CatalogTableUtil.buildWithConfig(factoryId, readonlyConfig);
            return Collections.singletonList(catalogTable);
        }

        Optional<Catalog> optionalCatalog =
                FactoryUtil.createOptionalCatalog(
                        factoryId, readonlyConfig, classLoader, factoryId);
        return optionalCatalog
                .map(
                        c -> {
                            try (Catalog catalog = c) {
                                long startTime = System.currentTimeMillis();
                                catalog.open();
                                List<CatalogTable> catalogTables =
                                        catalog.getTables(readonlyConfig);
                                log.info(
                                        String.format(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Either remove the empty schema block so the connector derives the schema from the catalog, or fill in complete schema fields (fields, fieldType)
2. Validate the config locally (e.g. seatunnel.sh --config ... -m localhost dry run) before submitting
3. If generating configs in code, only set ConnectorCommonOptions.SCHEMA when the map is non-empty

Example fix

// before
schema = {}
// after
schema = {
  fields {
    id = bigint
    name = string
  }
}

Map<String,Object> schema = config.get(ConnectorCommonOptions.SCHEMA);
if (schema != null && schema.isEmpty()) throw new IllegalArgumentException("schema block must not be empty");

try { tables = CatalogTableUtil.getCatalogTables(factoryId, cfg, cl); } catch (SeaTunnelException e) { /* inspect schema block */ }

When it happens

Trigger: Config contains schema = {} (or schema present with no fields/contents) for a connector; getCatalogTables detects schemaMap non-null but empty.

Common situations: HOCON config typo leaving an empty schema block; copying a template and deleting schema contents but not the key; programmatic config construction adding an empty SCHEMA map.

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

• CONNECT_DATABASE_FAILED
• '%s' must be configured when '%s' is used
• %s[%d]: '%s' must be configured
• Schema config need option [schema], please correct your conf
• Schema config can't contains both [fields] and [columns], pl

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