{"record":{"id":"9fe540d4cf8d285d","repo":"alibaba/canal","slug":"instance-config-is-not-found","errorCode":null,"errorMessage":"instance : {} config is not found","messagePattern":"instance : (.+?) config is not found","errorType":"exception","errorClass":"CanalException","httpStatus":null,"severity":"error","filePath":"instance/manager/src/main/java/com/alibaba/otter/canal/instance/manager/PlainCanalInstanceGenerator.java","lineNumber":43,"sourceCode":"public class PlainCanalInstanceGenerator implements CanalInstanceGenerator {\n\n    private static final Logger    logger      = LoggerFactory.getLogger(PlainCanalInstanceGenerator.class);\n    private String                 springXml;\n    private PlainCanalConfigClient canalConfigClient;\n    private String                 defaultName = \"instance\";\n    private BeanFactory            beanFactory;\n    private Properties             canalConfig;\n\n    public PlainCanalInstanceGenerator(Properties canalConfig){\n        this.canalConfig = canalConfig;\n    }\n\n    public CanalInstance generate(String destination) {\n        synchronized (CanalEventParser.class) {\n            try {\n                PlainCanal canal = canalConfigClient.findInstance(destination, null);\n                if (canal == null) {\n                    throw new CanalException(\"instance : \" + destination + \" config is not found\");\n                }\n                Properties properties = canal.getProperties();\n                // merge local\n                properties.putAll(canalConfig);\n\n                // 设置动态properties,替换掉本地properties\n                com.alibaba.otter.canal.instance.spring.support.PropertyPlaceholderConfigurer.propertiesLocal.set(properties);\n                // 设置当前正在加载的通道，加载spring查找文件时会用到该变量\n                System.setProperty(\"canal.instance.destination\", destination);\n                this.beanFactory = getBeanFactory(springXml);\n                String beanName = destination;\n                if (!beanFactory.containsBean(beanName)) {\n                    beanName = defaultName;\n                }\n\n                return (CanalInstance) beanFactory.getBean(beanName);\n            } catch (Throwable e) {\n                logger.error(\"generator instance failed.\", e);","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/instance/manager/src/main/java/com/alibaba/otter/canal/instance/manager/PlainCanalInstanceGenerator.java#L25-L61","documentation":"Thrown by PlainCanalInstanceGenerator.generate(destination) (PlainCanalInstanceGenerator.java:42-43) when canalConfigClient.findInstance(destination, null) returns null — i.e. the canal-manager server has no instance configuration registered under the requested destination name. CanalException text: 'instance : <destination> config is not found'. The generator runs in manager-mode canal (canal.instance.global.mode=manager), where each destination's properties are fetched from a remote config server rather than a local file.","triggerScenarios":"Starting a canal instance whose destination has not been created on the canal-manager config server (or was deleted), or whose destination name does not match any record. findInstance returning null triggers the throw before any Spring context is built.","commonSituations":"Destination name typo between the deployer startup argument and the manager record; manager DB not seeded / instance record not created; wrong canal-manager URL configured (canalmanager pointing at the wrong host so the lookup silently finds nothing); running in manager mode when you intended file mode; instance was disabled/deleted on the manager UI.","solutions":["On the canal-manager web UI (or its backing DB), create an instance configuration for the exact destination name and ensure it is enabled.","Verify canal.manager.canalAddress / canal.manager address and credentials in canal.properties so findInstance queries the right server.","Confirm the destination passed to the canal deployer matches the instance name in the manager (case-sensitive).","If you intended file-mode configuration, set canal.instance.global.mode = file and place <destination>/instance.properties under conf/ instead of relying on the manager.","Check the manager server logs / DB connectivity from the canal node — a findInstance that fails open (returns null) due to a backend error can mimic a missing record."],"exampleFix":"# before — manager mode, destination not registered\ncanal.instance.global.mode = manager\n# canal.deployer started with -destination=order_db\n# (no 'order_db' record on canal-manager)\n\n# after — either register the instance on the manager, or switch to file mode\ncanal.instance.global.mode = file\n# conf/order_db/instance.properties created","handlingStrategy":"validation","validationCode":"// In manager mode, confirm the destination is registered before starting the deployer\nPlainCanal canal = canalConfigClient.findInstance(destination, null);\nif (canal == null) {\n    throw new IllegalStateException(\n        \"destination '\" + destination + \"' is not registered on canal-manager at \" + managerAddress);\n}","typeGuard":null,"tryCatchPattern":"try {\n    generator.generate(destination);\n} catch (CanalException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"config is not found\")) {\n        log.error(\"destination {} not found on manager {}; create it or switch to file mode\",\n            destination, managerAddress);\n    }\n    throw e;\n}","preventionTips":["Create/enable the instance record on canal-manager for the exact destination name (case-sensitive).","Verify canal.manager address and credentials in canal.properties.","If file-mode is intended, set canal.instance.global.mode = file and place conf/<destination>/instance.properties.","Monitor manager DB connectivity — findInstance failing open can look like a missing record."],"tags":["configuration","manager","instance-generator","destination","initialization"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}