alibaba/canal · error · RuntimeException

not allow to change outAdapterKey

Error message

not allow to change outAdapterKey

What it means

Thrown by TablestoreAdapter.updateConfig() when a config update provides an outerAdapterKey that differs from the adapter's own configuration.getKey(). The outerAdapterKey is the binding that links a mapping config to its adapter instance; changing it at runtime would orphan the config from its writer infrastructure and break the adapter-config relationship, so the adapter rejects the change.

Source

Thrown at client-adapter/tablestore/src/main/java/com/alibaba/otter/canal/client/adapter/tablestore/TablestoreAdapter.java:327

        config2writerMap.put(configName, writer);
    }

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

    public void deleteConfig(String fileName) {
        tablestoreMapping.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. Ensure the updated mapping config's outerAdapterKey matches the adapter's existing configuration key exactly.
2. If the key genuinely needs to change, remove the old config first via deleteConfig(), then add the new one via addConfig() with the matching key.
3. Audit config file changes before hot-reloading — particularly the outerAdapterKey field.

Example fix

// before: config update with mismatched key
// adapter key: 'ts-prod'
// config.getOuterAdapterKey(): 'ts-dev'
adapter.updateConfig(fileName, config); // throws

// after: ensure key matches
config.setOuterAdapterKey("ts-prod");
adapter.updateConfig(fileName, config);

// Before calling updateConfig, verify the key matches
if (config.getOuterAdapterKey() != null
    && !config.getOuterAdapterKey().equals(configuration.getKey())) {
    throw new IllegalStateException(
        "Cannot update config: outerAdapterKey '" + config.getOuterAdapterKey()
        + "' does not match adapter key '" + configuration.getKey() + "'");
}
adapter.updateConfig(fileName, config);

null

try {
    adapter.updateConfig(fileName, config);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("not allow to change outAdapterKey")) {
        logger.error("Config key mismatch on update. Expected: {}, got: {}",
            configuration.getKey(), config.getOuterAdapterKey());
    }
    throw e;
}

When it happens

Trigger: Calling updateConfig(fileName, config) where config.getOuterAdapterKey() is non-null and not equal to the adapter's configuration.getKey() — typically when a hot-reload of a modified mapping YAML introduces a different or incorrect outerAdapterKey.

Common situations: An operator edits a tablestore mapping YAML and inadvertently changes or removes the outerAdapterKey field; a config management tool pushes a new YAML with a corrected/mistyped key; copy-paste between environments (dev→prod) without updating the key.

Related errors

• No tablestore adapter found for config key: {key}
• ERROR Config: {fileName} {errorMessage}
• dbMapping.database
• dbMapping.table
• dbMapping.targetTable

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