{"record":{"id":"48adb16b53ea8459","repo":"alibaba/canal","slug":"target-column-not-matched","errorCode":null,"errorMessage":"Target column: {} not matched","messagePattern":"Target column: (.+?) not matched","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"client-adapter/clickhouse/src/main/java/com/alibaba/otter/canal/client/adapter/clickhouse/service/ClickHouseBatchSyncService.java","lineNumber":325,"sourceCode":"            insertSql.append(\"?,\");\n        }\n        len = insertSql.length();\n        insertSql.delete(len - 1, len).append(\")\");\n\n        Map<String, Integer> ctype = getTargetColumnType(batchExecutor.getConn(), config);\n\n        List<List<Map<String, ?>>> values = new ArrayList<>();\n        boolean flag = false;\n        for (Map.Entry<String, String> entry : columnsMap.entrySet()) {\n            String targetColumnName = entry.getKey();\n            String srcColumnName = entry.getValue();\n            if (srcColumnName == null) {\n                srcColumnName = Util.cleanColumn(targetColumnName);\n            }\n\n            Integer type = ctype.get(Util.cleanColumn(targetColumnName).toLowerCase());\n            if (type == null) {\n                throw new RuntimeException(\"Target column: \" + targetColumnName + \" not matched\");\n            }\n            for (int i = 0; i < clearDmls.size(); i++) {\n                Map<String, Object> dmlData = clearDmls.get(i).getData();\n                List<Map<String, ?>> item;\n                if (flag == false) {\n                    item = new ArrayList<>();\n                    values.add(item);\n                } else {\n                    item = values.get(i);\n                }\n                Object value = dmlData.get(srcColumnName);\n                BatchExecutor.setValue(item, type, value);\n            }\n            flag = true;\n        }\n\n        try {\n            batchExecutor.batchExecute(insertSql.toString(), values);","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/client-adapter/clickhouse/src/main/java/com/alibaba/otter/canal/client/adapter/clickhouse/service/ClickHouseBatchSyncService.java#L307-L343","documentation":"Thrown by ClickHouseBatchSyncService.insert during a batch INSERT sync when a column present in the computed columnsMap (derived from targetColumns mapping or source data) has no matching entry in the target ClickHouse table's column-type map (ctype). This means the mapping references a target column that does not exist (under that name/casing) in the destination ClickHouse table.","triggerScenarios":"The targetColumns mapping names a column not present in the ClickHouse target table; the target table schema was altered (column dropped/renamed) after the mapping was written; case mismatch between the mapping column name and the ClickHouse column when caseInsensitive is off; mapAll mode including a source column whose derived target name is absent from the target table.","commonSituations":"Source schema evolved (new column) but ClickHouse target table not migrated; targetColumns map pointing at a renamed/deleted ClickHouse column; case sensitivity mismatch (ClickHouse column is lowercase, mapping uses mixed case) with caseInsensitive=false; typos in targetColumns keys.","solutions":["Compare the mapping's target column names against the actual ClickHouse table columns (DESCRIBE TABLE) and fix any mismatch.","Align casing: enable dbMapping.caseInsensitive=true if the target is case-insensitive, or correct the case in targetColumns.","If the source gained a column, add the corresponding column to the ClickHouse target table (ALTER TABLE ADD COLUMN).","Remove stale entries from targetColumns that reference non-existent target columns.","When using mapAll, ensure every mapped source column has a corresponding target column."],"exampleFix":"# before (mapping targetColumns references 'user_id' but ClickHouse table has 'userid'):\ndbMapping:\n  targetColumns:\n    user_id: user_id\n# after:\nALTER TABLE target_table ADD COLUMN user_id ...;\n# or correct the mapping:\ndbMapping:\n  targetColumns:\n    userid: userid","handlingStrategy":"validation","validationCode":"// Before enabling sync, verify every mapped target column exists in the ClickHouse table.\n// (Mirrors the internal ctype lookup that throws.)\ntry (Connection conn = dataSource.getConnection();\n     Statement st = conn.createStatement();\n     ResultSet rs = st.executeQuery(\"DESCRIBE TABLE \" + targetTable)) {\n    Set<String> cols = new HashSet<>();\n    while (rs.next()) cols.add(rs.getString(1).toLowerCase());\n    for (String mapped : targetColumnsMap.keySet()) {\n        if (!cols.contains(mapped.toLowerCase())) {\n            throw new IllegalStateException(\"Mapped target column '\" + mapped + \"' missing from \" + targetTable);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    adapter.sync(dmls);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"not matched\")) {\n        logger.error(\"Target column mismatch; run DESCRIBE TABLE and align mapping/case.\");\n    }\n    throw e;\n}","preventionTips":["Keep the ClickHouse target table schema in sync with the source; run ALTER TABLE on source DDL changes.","Validate targetColumns keys against DESCRIBE TABLE before enabling sync.","Enable dbMapping.caseInsensitive=true if the target is case-insensitive, or fix casing in the mapping.","When using mapAll, ensure every source column has a matching target column.","Remove stale targetColumns entries after renaming/dropping target columns."],"tags":["clickhouse-adapter","canal-adapter","schema-mismatch","sync","column-mapping"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}