{"record":{"id":"70074b0770a037af","repo":"alibaba/canal","slug":"not-allow-to-change-outadapterkey-70074b","errorCode":null,"errorMessage":"not allow to change outAdapterKey","messagePattern":"not allow to change outAdapterKey","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"client-adapter/phoenix/src/main/java/com/alibaba/otter/canal/client/adapter/phoenix/PhoenixAdapter.java","lineNumber":301,"sourceCode":"        configMap.put(configName, mappingConfig);\n    }\n\n    public boolean addConfig(String fileName, MappingConfig config) {\n        if (match(config)) {\n            phoenixMapping.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        phoenixMapping.put(fileName, config);\n        addSyncConfigToCache(fileName, config);\n    }\n\n    public void deleteConfig(String fileName) {\n        phoenixMapping.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":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/client-adapter/phoenix/src/main/java/com/alibaba/otter/canal/client/adapter/phoenix/PhoenixAdapter.java#L283-L319","documentation":"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.","triggerScenarios":"A runtime config monitor reloads a phoenix yml whose outerAdapterKey is non-null and not equal to configuration.getKey(), then calls updateConfig().","commonSituations":"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.","solutions":["Revert the 'outerAdapterKey:' edit so it matches the adapter's key.","To legitimately change the key, stop the launcher, update both application.yml and the yml, and restart."],"exampleFix":"# before (adapter bound to key 'phoenix')\nouterAdapterKey: phoenix2\n# after\nouterAdapterKey: phoenix","handlingStrategy":"validation","validationCode":"if (config.getOuterAdapterKey() != null\n        && !config.getOuterAdapterKey().equals(configuration.getKey())) {\n    logger.warn(\"Skip reload of {}: outerAdapterKey immutable at runtime\", fileName);\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    adapter.updateConfig(fileName, newConfig);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"not allow to change outAdapterKey\")) {\n        logger.warn(\"Skipped hot reload of {}: restart to rebind key\", fileName);\n    } else throw e;\n}","preventionTips":["Treat outerAdapterKey as immutable at runtime; only change it via restart.","Lock the 'outerAdapterKey:' line in config templates to prevent accidental edits."],"tags":["phoenix","config-update","hot-reload","canal"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}