apache/seatunnel · error · FileConnectorException

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

Error message

Incompatible Markdown Knowledge Sync metadata column: %s

What it means

MarkdownKnowledgeSyncMetadata.withMetadata merges built-in metadata columns (e.g. file path/name/ modification metadata for Markdown knowledge sync) into the CatalogTable. If a metadata column name collides with an existing column whose data type or nullability differs, it throws CONFIG_VALIDATION_FAILED with the offending column name (MarkdownKnowledgeSyncMetadata.java:190).

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/MarkdownKnowledgeSyncMetadata.java:190

    /** Merges registry-defined Markdown bridge metadata into a catalog table. */
    public static CatalogTable withMetadata(CatalogTable catalogTable) {
        List<Column> mergedColumns = new ArrayList<>(catalogTable.getMetadataSchema().getColumns());
        Map<String, Column> existingColumns = new HashMap<>();
        for (Column column : mergedColumns) {
            existingColumns.putIfAbsent(column.getName(), column);
        }

        for (KnowledgeSyncMetadataField field : BRIDGE_FIELDS) {
            MetadataColumn bridgeColumn = field.toMetadataColumn();
            Column existingColumn = existingColumns.get(field.getName());
            if (existingColumn == null) {
                mergedColumns.add(bridgeColumn);
                existingColumns.put(field.getName(), bridgeColumn);
                continue;
            }
            if (!bridgeColumn.getDataType().equals(existingColumn.getDataType())
                    || bridgeColumn.isNullable() != existingColumn.isNullable()) {
                throw new FileConnectorException(
                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                        "Incompatible Markdown Knowledge Sync metadata column: " + field.getName());
            }
        }

        return CatalogTable.withMetadata(
                catalogTable, MetadataSchema.builder().columns(mergedColumns).build());
    }

    private static boolean looksLikeUri(String sourceUri) {
        int colon = sourceUri.indexOf(':');
        if (colon <= 0 || !Character.isLetter(sourceUri.charAt(0))) {
            return false;
        }
        for (int i = 1; i < colon; i++) {
            char value = sourceUri.charAt(i);
            if (!Character.isLetterOrDigit(value) && value != '+' && value != '-' && value != '.') {
                return false;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Rename your column so it doesn't collide with the metadata column name.
2. Or match the metadata column's exact DataType and nullability so the merge succeeds.
3. List the built-in metadata columns in MarkdownKnowledgeSyncMetadata and avoid those names in your schema.
4. Re-check the schema after any metadata-column changes in connector upgrades.

Example fix

// before
schema = { fields { path string, value string } }  // path conflicts with metadata map type
// after
schema = { fields { source_path string, value string } }

// Check collisions before building the CatalogTable
CatalogTable.LinearizedColumn meta = metadataColumns.get(name);
if (schema.containsField(name)
        && (!meta.getDataType().equals(schema.getField(name).getDataType())
            || meta.isNullable() != schema.getField(name).isNullable())) {
    throw new IllegalArgumentException("Column '" + name + "' conflicts with Markdown sync metadata column");
}

try {
    // withMetadata merge
} catch (FileConnectorException e) {
    if (SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED.equals(e.getErrorCode())
            && e.getMessage().contains("Markdown Knowledge Sync metadata column")) {
        throw new IllegalStateException("Rename the conflicting column or match metadata type/nullability", e);
    }
    throw e;
}

When it happens

Trigger: User-defined schema (or table schema) declares a column with the same name as a Markdown Knowledge Sync metadata bridge column but a different DataType or isNullable value; withMetadata is called while building the CatalogTable.

Common situations: Naming a data column like the metadata column (e.g. `path`, file-related fields) with a different type (string vs map) or making it non-nullable while the metadata column is nullable; schema templates copied between jobs.

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

• Failed to read schema for table %s
• TABLE_SCHEMA_GET_FAILED
• Failed to query table schema: {}
• Operator %s requires a compareOption (cross-field comparison
• Operator %s requires an expectValue, but expectValue is null

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