alibaba/canal · error · NullPointerException

dbMapping.database

Error message

dbMapping.database

What it means

Thrown as NullPointerException by MappingConfig.validate when dbMapping.database is null or empty. database (the source database/schema name) is the one universally required field for every clickhouse mapping, mirrorDb or not. ConfigLoader catches it and re-throws as 'ERROR Config: <file> dbMapping.database'.

Source

Thrown at client-adapter/clickhouse/src/main/java/com/alibaba/otter/canal/client/adapter/clickhouse/config/MappingConfig.java:86

    public void setDbMapping(DbMapping dbMapping) {
        this.dbMapping = dbMapping;
    }

    public String getDestination() {
        return destination;
    }

    public void setDestination(String destination) {
        this.destination = destination;
    }

    public AdapterMapping getMapping() {
        return dbMapping;
    }

    public void validate() {
        if (dbMapping.database == null || dbMapping.database.isEmpty()) {
            throw new NullPointerException("dbMapping.database");
        }
        if (!dbMapping.getMirrorDb() && (dbMapping.table == null || dbMapping.table.isEmpty())) {
            throw new NullPointerException("dbMapping.table");
        }
        if (!dbMapping.getMirrorDb() && (dbMapping.targetTable == null || dbMapping.targetTable.isEmpty())) {
            throw new NullPointerException("dbMapping.targetTable");
        }
    }

    public static class DbMapping implements AdapterMapping {

        private boolean             mirrorDb        = false;                 // 是否镜像库
        private String              database;                                // 数据库名或schema名
        private String              table;                                   // 表名
        private Map<String, String> targetPk        = new LinkedHashMap<>(); // 目标表主键字段
        private boolean             mapAll          = false;                 // 映射所有字段
        private String              targetDb;                                // 目标库名
        private String              targetTable;                             // 目标表名

View on GitHub (pinned to 87be50e876)

Solutions

1. Add a non-empty database value under dbMapping in the named yml file.
2. Verify YAML indentation so database is a child of dbMapping.
3. Cross-check against a known-good mapping file in the repo.
4. Restart the adapter to reload.

Example fix

# before:
dbMapping:
  table: orders
  targetTable: orders
# after:
dbMapping:
  database: shop
  table: orders
  targetTable: orders

// Pre-flight check before adapter init.
MappingConfig.DbMapping m = config.getDbMapping();
if (m == null || m.getDatabase() == null || m.getDatabase().isEmpty()) {
    throw new IllegalArgumentException("dbMapping.database is required (file: " + fileName + ")");
}

When it happens

Trigger: A mapping yml with a dbMapping block that omits the database key; database set to an empty string; YAML indentation placing database outside the dbMapping map so it binds null.

Common situations: Template config with database left as a placeholder; indentation error nesting database under the wrong key; renamed field during a config refactor.

Related errors

• dbMapping.table
• dbMapping.targetTable
• ERROR Config: {} {}
• No clickhouse adapter found for config key: {}
• not allow to change outAdapterKey

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/a63189d3838c06b3. Report an issue: GitHub.