alibaba/canal · error · NullPointerException

hbaseMapping.database

Error message

hbaseMapping.database

What it means

MappingConfig.validate() requires HbaseMapping.database to be a non-null, non-empty string (the source MySQL/database or schema name). A null or empty database fails validation with this NullPointerException.

Source

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

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

    public HbaseMapping getHbaseMapping() {
        return hbaseMapping;
    }

    public void setHbaseMapping(HbaseMapping hbaseMapping) {
        this.hbaseMapping = hbaseMapping;
    }

    public AdapterMapping getMapping() {
        return hbaseMapping;
    }

    public void validate() {
        if (hbaseMapping.database == null || hbaseMapping.database.isEmpty()) {
            throw new NullPointerException("hbaseMapping.database");
        }
        if (hbaseMapping.table == null || hbaseMapping.table.isEmpty()) {
            throw new NullPointerException("hbaseMapping.table");
        }
        if (hbaseMapping.hbaseTable == null || hbaseMapping.hbaseTable.isEmpty()) {
            throw new NullPointerException("hbaseMapping.hbaseTable");
        }
        if (hbaseMapping.mode == null) {
            throw new NullPointerException("hbaseMapping.mode");
        }
        if (hbaseMapping.rowKey != null && hbaseMapping.rowKeyColumn != null) {
            throw new RuntimeException("已配置了复合主键作为RowKey，无需再指定RowKey列");
        }
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;

View on GitHub (pinned to 87be50e876)

Solutions

  1. Add 'database: <your_source_db_name>' under hbaseMapping in the mapping YAML.
  2. Verify YAML indentation (database must be nested under hbaseMapping, two-space indent).
  3. Validate the YAML with a linter before deploying.
  4. Check that the database value is not quoted-empty ('').

Example fix

# before
hbaseMapping:
  table: t_user
  hbaseTable: user

# after
hbaseMapping:
  database: mydb
  table: t_user
  hbaseTable: user
Defensive patterns

Strategy: validation

Validate before calling

// Validate before adapter startup
MappingConfig cfg = YamlUtils.ymlToObj(null, content, MappingConfig.class, null, env);
if (cfg.getHbaseMapping() == null
        || cfg.getHbaseMapping().getDatabase() == null
        || cfg.getHbaseMapping().getDatabase().isEmpty()) {
    throw new IllegalArgumentException("hbaseMapping.database is required");
}

Try / catch

try {
    config.validate();
} catch (NullPointerException e) {
    if ("hbaseMapping.database".equals(e.getMessage())) {
        logger.error("Add 'database: <db>' under hbaseMapping in the YAML");
    }
    throw e;
}

Prevention

When it happens

Trigger: Loading an HBase mapping YAML that omits 'hbaseMapping.database' or sets it to an empty string; config.validate() is called by MappingConfigLoader.load() during adapter startup.

Common situations: Newly authored or copy-pasted HBase mapping YAML missing the database line; YAML indentation error causing database to be parsed as null.

Related errors

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