alibaba/canal · error · NullPointerException

hbaseMapping.mode

Error message

hbaseMapping.mode

What it means

MappingConfig.validate() requires HbaseMapping.mode (one of STRING/NATIVE/PHOENIX) to be non-null. Note HbaseMapping defaults mode to STRING, so hitting this means the YAML explicitly set mode to null or the value failed to deserialize into the Mode enum.

Source

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

        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;
        if (o == null || getClass() != o.getClass()) return false;

        MappingConfig config = (MappingConfig) o;

        return hbaseMapping != null ? hbaseMapping.equals(config.hbaseMapping) : config.hbaseMapping == null;
    }

    @Override
    public int hashCode() {

View on GitHub (pinned to 87be50e876)

Solutions

1. Set 'mode: STRING' (or NATIVE/PHOENIX) explicitly, or omit 'mode' to use the STRING default.
2. Confirm the mode value matches the enum constant exactly (case-sensitive).
3. Verify the canal version supports the chosen mode enum value.
4. Lint the YAML.

Example fix

# before (invalid mode)
hbaseMapping:
  mode: STRING_TYPE

# after
hbaseMapping:
  mode: STRING

MappingConfig cfg = ...;
if (cfg.getHbaseMapping() == null || cfg.getHbaseMapping().getMode() == null) {
    throw new IllegalArgumentException("hbaseMapping.mode must be STRING, NATIVE, or PHOENIX");
}

try {
    config.validate();
} catch (NullPointerException e) {
    if ("hbaseMapping.mode".equals(e.getMessage())) {
        logger.error("Set mode: STRING|NATIVE|PHOENIX or omit to default to STRING");
    }
    throw e;
}

When it happens

Trigger: HBase mapping YAML setting 'mode:' to null or to a value that is not STRING/NATIVE/PHOENIX (which would actually throw on enum binding); validate() during load.

Common situations: Setting an invalid mode string in the YAML; removing the default via explicit null; older canal version whose enum lacks PHOENIX.

Related errors

• hbaseMapping.database
• hbaseMapping.table
• hbaseMapping.hbaseTable
• 已配置了复合主键作为RowKey，无需再指定RowKey列
• clusterId and serverId are all empty

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