{"record":{"id":"9eb1c96b857e2dfc","repo":"alibaba/canal","slug":"not-allow-to-change-outadapterkey-9eb1c9","errorCode":null,"errorMessage":"not allow to change outAdapterKey","messagePattern":"not allow to change outAdapterKey","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"client-adapter/hbase/src/main/java/com/alibaba/otter/canal/client/adapter/hbase/HbaseAdapter.java","lineNumber":244,"sourceCode":"        configMap.put(configName, mappingConfig);\n    }\n\n    public boolean addConfig(String fileName, MappingConfig config) {\n        if (match(config)) {\n            hbaseMapping.put(fileName, config);\n            addSyncConfigToCache(fileName, config);\n            FileName2KeyMapping.register(getClass().getAnnotation(SPI.class).value(), fileName,\n                    configuration.getKey());\n            return true;\n        }\n        return false;\n    }\n\n    public void updateConfig(String fileName, MappingConfig config) {\n        if (config.getOuterAdapterKey() != null && !config.getOuterAdapterKey()\n                .equals(configuration.getKey())) {\n            // 理论上不允许改这个 因为本身就是通过这个关联起Adapter和Config的\n            throw new RuntimeException(\"not allow to change outAdapterKey\");\n        }\n        hbaseMapping.put(fileName, config);\n        addSyncConfigToCache(fileName, config);\n    }\n\n    public void deleteConfig(String fileName) {\n        hbaseMapping.remove(fileName);\n        for (Map<String, MappingConfig> configMap : mappingConfigCache.values()) {\n            if (configMap != null) {\n                configMap.remove(fileName);\n            }\n        }\n        FileName2KeyMapping.unregister(getClass().getAnnotation(SPI.class).value(), fileName);\n    }\n\n    private boolean match(MappingConfig config) {\n        boolean sameMatch = config.getOuterAdapterKey() != null && config.getOuterAdapterKey()\n                .equalsIgnoreCase(configuration.getKey());","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/client-adapter/hbase/src/main/java/com/alibaba/otter/canal/client/adapter/hbase/HbaseAdapter.java#L226-L262","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["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.","If you intend to reassign the key, restart the adapter rather than hot-reloading.","Diff the new YAML against the original and confirm only non-key fields changed.","Check the adapter's registered key in the canal instance configuration matches the mapping's outerAdapterKey."],"exampleFix":"# before (changed key)\nhbaseMapping:\n  outerAdapterKey: hbase-cluster-B   # was hbase-cluster-A\n\n# after (keep the original key)\nhbaseMapping:\n  outerAdapterKey: hbase-cluster-A","handlingStrategy":"validation","validationCode":"// Before hot-reload, confirm outerAdapterKey is unchanged\nMappingConfig old = hbaseMapping.get(fileName);\nif (old != null && newConfig.getOuterAdapterKey() != null\n        && !newConfig.getOuterAdapterKey().equals(configuration.getKey())) {\n    throw new IllegalStateException(\"Refusing to change outerAdapterKey; delete and re-add instead\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    adapter.updateConfig(fileName, config);\n} catch (RuntimeException e) {\n    if (\"not allow to change outAdapterKey\".equals(e.getMessage())) {\n        logger.error(\"outerAdapterKey changed; revert it or delete+addConfig instead\");\n    }\n    throw e;\n}","preventionTips":["Never edit outerAdapterKey of a deployed mapping; restart the adapter to reassign.","Version-control mapping YAMLs and review diffs before hot-reload.","To move a config, deleteConfig first then addConfig on the target adapter."],"tags":["hbase-adapter","config","hot-reload","adapter-key"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}