{"record":{"id":"324bd074854da3c4","repo":"apache/seatunnel","slug":"seatunnelapierrorcode-config-validation-failed","errorCode":"SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED","errorMessage":"Incompatible Markdown Knowledge Sync metadata column: %s","messagePattern":"Incompatible Markdown Knowledge Sync metadata column: (.+?)","errorType":"error_code","errorClass":"FileConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/MarkdownKnowledgeSyncMetadata.java","lineNumber":190,"sourceCode":"    /** Merges registry-defined Markdown bridge metadata into a catalog table. */\n    public static CatalogTable withMetadata(CatalogTable catalogTable) {\n        List<Column> mergedColumns = new ArrayList<>(catalogTable.getMetadataSchema().getColumns());\n        Map<String, Column> existingColumns = new HashMap<>();\n        for (Column column : mergedColumns) {\n            existingColumns.putIfAbsent(column.getName(), column);\n        }\n\n        for (KnowledgeSyncMetadataField field : BRIDGE_FIELDS) {\n            MetadataColumn bridgeColumn = field.toMetadataColumn();\n            Column existingColumn = existingColumns.get(field.getName());\n            if (existingColumn == null) {\n                mergedColumns.add(bridgeColumn);\n                existingColumns.put(field.getName(), bridgeColumn);\n                continue;\n            }\n            if (!bridgeColumn.getDataType().equals(existingColumn.getDataType())\n                    || bridgeColumn.isNullable() != existingColumn.isNullable()) {\n                throw new FileConnectorException(\n                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,\n                        \"Incompatible Markdown Knowledge Sync metadata column: \" + field.getName());\n            }\n        }\n\n        return CatalogTable.withMetadata(\n                catalogTable, MetadataSchema.builder().columns(mergedColumns).build());\n    }\n\n    private static boolean looksLikeUri(String sourceUri) {\n        int colon = sourceUri.indexOf(':');\n        if (colon <= 0 || !Character.isLetter(sourceUri.charAt(0))) {\n            return false;\n        }\n        for (int i = 1; i < colon; i++) {\n            char value = sourceUri.charAt(i);\n            if (!Character.isLetterOrDigit(value) && value != '+' && value != '-' && value != '.') {\n                return false;","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/MarkdownKnowledgeSyncMetadata.java#L172-L208","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rename your column so it doesn't collide with the metadata column name.","Or match the metadata column's exact DataType and nullability so the merge succeeds.","List the built-in metadata columns in MarkdownKnowledgeSyncMetadata and avoid those names in your schema.","Re-check the schema after any metadata-column changes in connector upgrades."],"exampleFix":"// before\nschema = { fields { path string, value string } }  // path conflicts with metadata map type\n// after\nschema = { fields { source_path string, value string } }","handlingStrategy":"validation","validationCode":"// Check collisions before building the CatalogTable\nCatalogTable.LinearizedColumn meta = metadataColumns.get(name);\nif (schema.containsField(name)\n        && (!meta.getDataType().equals(schema.getField(name).getDataType())\n            || meta.isNullable() != schema.getField(name).isNullable())) {\n    throw new IllegalArgumentException(\"Column '\" + name + \"' conflicts with Markdown sync metadata column\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // withMetadata merge\n} catch (FileConnectorException e) {\n    if (SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED.equals(e.getErrorCode())\n            && e.getMessage().contains(\"Markdown Knowledge Sync metadata column\")) {\n        throw new IllegalStateException(\"Rename the conflicting column or match metadata type/nullability\", e);\n    }\n    throw e;\n}","preventionTips":["Reserve metadata column names in user schemas.","Keep metadata column types synchronized with the connector version.","Add a unit test that merges every user schema with metadata columns."],"tags":["schema","metadata","conflict"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}