alibaba/canal · error · RuntimeException

not allow to change outAdapterKey

Error message

not allow to change outAdapterKey

What it means

HbaseAdapter.updateConfig() rejects a hot-reloaded HBase mapping config whose outerAdapterKey differs from the key the adapter was registered under. The outerAdapterKey is the binding between a MappingConfig and its HbaseAdapter instance, so changing it at runtime would orphan the config.

Source

Thrown at client-adapter/hbase/src/main/java/com/alibaba/otter/canal/client/adapter/hbase/HbaseAdapter.java:244

        configMap.put(configName, mappingConfig);
    }

    public boolean addConfig(String fileName, MappingConfig config) {
        if (match(config)) {
            hbaseMapping.put(fileName, config);
            addSyncConfigToCache(fileName, config);
            FileName2KeyMapping.register(getClass().getAnnotation(SPI.class).value(), fileName,
                    configuration.getKey());
            return true;
        }
        return false;
    }

    public void updateConfig(String fileName, MappingConfig config) {
        if (config.getOuterAdapterKey() != null && !config.getOuterAdapterKey()
                .equals(configuration.getKey())) {
            // 理论上不允许改这个 因为本身就是通过这个关联起Adapter和Config的
            throw new RuntimeException("not allow to change outAdapterKey");
        }
        hbaseMapping.put(fileName, config);
        addSyncConfigToCache(fileName, config);
    }

    public void deleteConfig(String fileName) {
        hbaseMapping.remove(fileName);
        for (Map<String, MappingConfig> configMap : mappingConfigCache.values()) {
            if (configMap != null) {
                configMap.remove(fileName);
            }
        }
        FileName2KeyMapping.unregister(getClass().getAnnotation(SPI.class).value(), fileName);
    }

    private boolean match(MappingConfig config) {
        boolean sameMatch = config.getOuterAdapterKey() != null && config.getOuterAdapterKey()
                .equalsIgnoreCase(configuration.getKey());

View on GitHub (pinned to 87be50e876)

Solutions

  1. Keep the outerAdapterKey unchanged when editing an existing mapping file; to move a config between adapters, delete it first then addConfig on the target adapter.
  2. If you intend to reassign the key, restart the adapter rather than hot-reloading.
  3. Diff the new YAML against the original and confirm only non-key fields changed.
  4. Check the adapter's registered key in the canal instance configuration matches the mapping's outerAdapterKey.

Example fix

# before (changed key)
hbaseMapping:
  outerAdapterKey: hbase-cluster-B   # was hbase-cluster-A

# after (keep the original key)
hbaseMapping:
  outerAdapterKey: hbase-cluster-A
Defensive patterns

Strategy: validation

Validate before calling

// Before hot-reload, confirm outerAdapterKey is unchanged
MappingConfig old = hbaseMapping.get(fileName);
if (old != null && newConfig.getOuterAdapterKey() != null
        && !newConfig.getOuterAdapterKey().equals(configuration.getKey())) {
    throw new IllegalStateException("Refusing to change outerAdapterKey; delete and re-add instead");
}

Try / catch

try {
    adapter.updateConfig(fileName, config);
} catch (RuntimeException e) {
    if ("not allow to change outAdapterKey".equals(e.getMessage())) {
        logger.error("outerAdapterKey changed; revert it or delete+addConfig instead");
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling HbaseAdapter.updateConfig(fileName, config) after editing the mapping YAML so that 'outerAdapterKey' now points to a different adapter key than the one stored in this adapter's configuration.getKey().

Common situations: Editing a running HBase adapter's mapping YAML and changing the outerAdapterKey; copying a config file from another adapter and reloading it; mis-typing the adapter key.

Related errors

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