apache/seatunnel · error · RuntimeException

Schema config need option [schema], please correct your conf

Error message

Schema config need option [schema], please correct your config first

What it means

CatalogTableUtil.buildWithConfig requires the 'schema' option to construct a CatalogTable manually. When the config lacks ConnectorCommonOptions.SCHEMA entirely, it throws RuntimeException telling the user to add the schema block.

Source

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

                        CatalogTableUtil.getCatalogTable(
                                id, ((MultipleRowType) seaTunnelDataType).getRowType(id)));
            }
        } else {
            catalogTables =
                    Collections.singletonList(
                            CatalogTableUtil.getCatalogTable(
                                    tableId, (SeaTunnelRowType) seaTunnelDataType));
        }
        return catalogTables;
    }

    public static CatalogTable buildWithConfig(ReadonlyConfig readonlyConfig) {
        return buildWithConfig("", readonlyConfig);
    }

    public static CatalogTable buildWithConfig(String catalogName, ReadonlyConfig readonlyConfig) {
        if (readonlyConfig.get(ConnectorCommonOptions.SCHEMA) == null) {
            throw new RuntimeException(
                    "Schema config need option [schema], please correct your config first");
        }
        TableSchema tableSchema = new ReadonlyConfigParser().parse(readonlyConfig);

        ReadonlyConfig schemaConfig =
                readonlyConfig
                        .getOptional(ConnectorCommonOptions.SCHEMA)
                        .map(ReadonlyConfig::fromMap)
                        .orElseThrow(
                                () -> new IllegalArgumentException("Schema config can't be null"));

        TablePath tablePath;
        if (StringUtils.isNotEmpty(schemaConfig.get(ConnectorCommonOptions.TABLE))) {
            tablePath =
                    TablePath.of(
                            schemaConfig.get(ConnectorCommonOptions.TABLE),
                            schemaConfig.get(ConnectorCommonOptions.SCHEMA_FIRST));
        } else {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add a schema block with fields to the connector config
2. If schema should be auto-derived, use the path that queries the catalog instead of buildWithConfig
3. In custom code, check readonlyConfig.get(ConnectorCommonOptions.SCHEMA) != null before calling buildWithConfig

Example fix

// before
source {
  FakeSource { }
}
// after
source {
  FakeSource {
    schema = {
      fields {
        id = int
        name = string
      }
    }
  }
}

if (readonlyConfig.get(ConnectorCommonOptions.SCHEMA) == null) { throw new IllegalArgumentException("config must define schema"); }

try { CatalogTable t = CatalogTableUtil.buildWithConfig(cfg); } catch (RuntimeException e) { /* add schema block */ }

When it happens

Trigger: Calling buildWithConfig (directly or via getCatalogTables' schema path / connectors requiring manual schema) with a ReadonlyConfig that has no 'schema' key.

Common situations: Older configs that relied on automatic schema retrieval but are now run through a code path requiring an explicit schema; custom code invoking buildWithConfig on user config that never defined schema; connector docs/examples missing the schema section.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Schema config can not be empty
• Schema config can't contains both [fields] and [columns], pl
• AzureCosmosDB requires uri, endpoint, or connection string t
• INVALID_PRIMARY_KEY
• UNSUPPORTED_OPERATION

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