{"record":{"id":"a048213923c1d7f7","repo":"alibaba/canal","slug":"target-column-targetcolumnname-not-matched-a04821","errorCode":null,"errorMessage":"Target column: {targetColumnName} not matched","messagePattern":"Target column: (.+?) not matched","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"client-adapter/rdb/src/main/java/com/alibaba/otter/canal/client/adapter/rdb/service/RdbSyncService.java","lineNumber":287,"sourceCode":"        for (int i = 0; i < mapLen; i++) {\n            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<Map<String, ?>> values = new ArrayList<>();\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            Object value = data.get(srcColumnName);\n            BatchExecutor.setValue(values, type, value);\n        }\n\n        try {\n            batchExecutor.execute(insertSql.toString(), values);\n        } catch (SQLException e) {\n            if (skipDupException\n                && (e.getMessage().contains(\"Duplicate entry\") || e.getMessage().contains(\"duplicate key\") || e.getMessage().startsWith(\"ORA-00001:\"))) {\n                // ignore\n                // TODO 增加更多关系数据库的主键冲突的错误码\n            } else {\n                throw e;\n            }\n        }\n        if (logger.isTraceEnabled()) {\n            logger.trace(\"Insert into target table, sql: {}\", insertSql);","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/client-adapter/rdb/src/main/java/com/alibaba/otter/canal/client/adapter/rdb/service/RdbSyncService.java#L269-L305","documentation":"Thrown during the INSERT sync path when a target column name declared in the RDB mapping config cannot be found in the target database table's metadata. The target column types are loaded once via getTargetColumnType(), which executes `SELECT * FROM targetTable WHERE 1=2` and caches column names (lowercased) under key `destination.database.table`. If the cleaned, lowercased target column name is absent from that metadata map, the sync aborts because Canal cannot determine the JDBC type needed for the prepared-statement parameter.","triggerScenarios":"Calling RdbSyncService.sync() (insert path) where dbMapping.targetColumns lists a column that does not exist in the target table, or where the target table schema was altered (column renamed/dropped) after the column-type cache was populated, or where a column name has case/quote/backtick differences that cleanColumn+toLowerCase cannot reconcile.","commonSituations":"Mapping YAML references a column name with a typo or wrong casing; target DDL was migrated (column renamed) but the canal mapping config was not updated; a column uses special characters that cleanColumn strips inconsistently; target DB connection points to a different schema/database than expected.","solutions":["Compare every key in the mapping config's targetColumns map against `DESC targetTable` or `SELECT * FROM targetTable WHERE 1=2` column names — fix any name that does not match.","If the target schema changed after canal started, restart the canal adapter instance so columnsTypeCache is rebuilt from the current DDL.","Verify the target database/schema in dbMapping.database and dbMapping.targetTable point to the correct target where the column actually exists.","Ensure target column names in the config contain no stray backticks, quotes, or whitespace — cleanColumn removes backticks and single-quotes but not double-quotes or trailing spaces."],"exampleFix":"// mapping config before (column 'user_name' does not exist in target table)\ntargetColumns:\n  user_name: username\n\n// after (corrected to match target table DDL)\ntargetColumns:\n  username: username","handlingStrategy":"validation","validationCode":"// Before sync, verify all target columns exist in the target table metadata\nConnection conn = batchExecutor.getConn();\nDbMapping dbMapping = config.getDbMapping();\nDatabaseMetaData meta = conn.getMetaData();\ntry (ResultSet rs = meta.getColumns(null, null, dbMapping.getTargetTable(), null)) {\n    Set<String> actualCols = new HashSet<>(String.CASE_INSENSITIVE_ORDER);\n    while (rs.next()) {\n        actualCols.add(rs.getString(\"COLUMN_NAME\"));\n    }\n}\nfor (String targetCol : dbMapping.getTargetColumns().keySet()) {\n    String cleaned = Util.cleanColumn(targetCol);\n    if (!actualCols.contains(cleaned)) {\n        throw new IllegalStateException(\n            \"Target column '\" + targetCol + \"' not found in table \" + dbMapping.getTargetTable());\n    }\n}","typeGuard":"null","tryCatchPattern":"// Wrap the sync call and report schema mismatches clearly\ntry {\n    rdbSyncService.sync(dmls);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Target column:\") && e.getMessage().contains(\"not matched\")) {\n        logger.error(\"Schema mismatch detected. Verify target table columns match mapping config: {}\", e.getMessage());\n        // trigger schema refresh by clearing cache and retrying once\n    }\n    throw e;\n}","preventionTips":["Run a config validation step at deployment that compares mapping config column names against the live target table DDL.","Restart the canal adapter after any target schema migration to rebuild the column-type cache.","Use a CI pipeline that validates mapping YAML column names against a schema definition before deploy."],"tags":["rdb-adapter","schema-mismatch","column-mapping","config-error"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}