alibaba/canal · error · NullPointerException

dbMapping.database

Error message

dbMapping.database

What it means

Thrown by MappingConfig.validate() when dbMapping.database is null or empty. This is one of three required fields validated in sequence (database, then table, then targetTable). validate() is called during ConfigLoader.load(), so this surfaces wrapped in the 'ERROR Config: {fileName}' RuntimeException. The exception type is NullPointerException despite being a validation check, not an unexpected null dereference.

Source

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

    public Boolean getUpdateChangeColumns() {
        return updateChangeColumns;
    }

    public void setUpdateChangeColumns(Boolean updateChangeColumns) {
        this.updateChangeColumns = updateChangeColumns;
    }

    public Integer getThreads() {
        return threads;
    }

    public void setThreads(Integer threads) {
        this.threads = threads;
    }

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




    public static class ColumnItem {
        private String targetColumn;
        private String  column;
        private TablestoreFieldType type;

        public String getColumn() {

View on GitHub (pinned to 87be50e876)

Solutions

1. Add a non-empty `database` value under the `dbMapping` key in the YAML config.
2. Verify YAML indentation — dbMapping children must be indented under dbMapping.
3. If using environment variable substitution, ensure the variable resolves to a non-empty value.

Example fix

// before
dbMapping:
  table: users
  targetTable: ots_users

// after
dbMapping:
  database: mydb
  table: users
  targetTable: ots_users

// Check dbMapping.database before calling validate()
if (config.getDbMapping() == null
    || config.getDbMapping().getDatabase() == null
    || config.getDbMapping().getDatabase().isEmpty()) {
    throw new IllegalArgumentException("dbMapping.database is required and must not be empty");
}

null

try {
    config.validate();
} catch (NullPointerException e) {
    if ("dbMapping.database".equals(e.getMessage())) {
        logger.error("Missing required field: dbMapping.database");
    }
    throw e;
}

When it happens

Trigger: Loading a tablestore mapping config YAML where the dbMapping.database field is absent, null, or an empty string. The validate() method checks this first and throws immediately.

Common situations: YAML file missing the `database:` line under dbMapping; indentation error places database at the wrong nesting level; template/config-generation tool omitted the field; environment-specific override file blanked out the value.

Related errors

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

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