alibaba/canal · error · RuntimeException

not allow to change outAdapterKey

Error message

not allow to change outAdapterKey

What it means

Thrown by PhoenixAdapter.updateConfig() when a hot-reloaded phoenix mapping yml has an outerAdapterKey that differs from the key this adapter was initialized with. outerAdapterKey binds a Config to its Adapter and cannot be changed on a running adapter.

Source

Thrown at client-adapter/phoenix/src/main/java/com/alibaba/otter/canal/client/adapter/phoenix/PhoenixAdapter.java:301

        configMap.put(configName, mappingConfig);
    }

    public boolean addConfig(String fileName, MappingConfig config) {
        if (match(config)) {
            phoenixMapping.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");
        }
        phoenixMapping.put(fileName, config);
        addSyncConfigToCache(fileName, config);
    }

    public void deleteConfig(String fileName) {
        phoenixMapping.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. Revert the 'outerAdapterKey:' edit so it matches the adapter's key.
2. To legitimately change the key, stop the launcher, update both application.yml and the yml, and restart.

Example fix

# before (adapter bound to key 'phoenix')
outerAdapterKey: phoenix2
# after
outerAdapterKey: phoenix

if (config.getOuterAdapterKey() != null
        && !config.getOuterAdapterKey().equals(configuration.getKey())) {
    logger.warn("Skip reload of {}: outerAdapterKey immutable at runtime", fileName);
    return;
}

try {
    adapter.updateConfig(fileName, newConfig);
} catch (RuntimeException e) {
    if (e.getMessage().contains("not allow to change outAdapterKey")) {
        logger.warn("Skipped hot reload of {}: restart to rebind key", fileName);
    } else throw e;
}

When it happens

Trigger: A runtime config monitor reloads a phoenix yml whose outerAdapterKey is non-null and not equal to configuration.getKey(), then calls updateConfig().

Common situations: Editing the 'outerAdapterKey:' line of a phoenix mapping file while the adapter is running, or copying a file between adapter dirs that the monitor then reloads.

Related errors

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

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