alibaba/canal · error · CanalException

instance : {} config is not found

Error message

instance : {} config is not found

What it means

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.

Source

Thrown at instance/manager/src/main/java/com/alibaba/otter/canal/instance/manager/PlainCanalInstanceGenerator.java:43

public class PlainCanalInstanceGenerator implements CanalInstanceGenerator {

    private static final Logger    logger      = LoggerFactory.getLogger(PlainCanalInstanceGenerator.class);
    private String                 springXml;
    private PlainCanalConfigClient canalConfigClient;
    private String                 defaultName = "instance";
    private BeanFactory            beanFactory;
    private Properties             canalConfig;

    public PlainCanalInstanceGenerator(Properties canalConfig){
        this.canalConfig = canalConfig;
    }

    public CanalInstance generate(String destination) {
        synchronized (CanalEventParser.class) {
            try {
                PlainCanal canal = canalConfigClient.findInstance(destination, null);
                if (canal == null) {
                    throw new CanalException("instance : " + destination + " config is not found");
                }
                Properties properties = canal.getProperties();
                // merge local
                properties.putAll(canalConfig);

                // 设置动态properties,替换掉本地properties
                com.alibaba.otter.canal.instance.spring.support.PropertyPlaceholderConfigurer.propertiesLocal.set(properties);
                // 设置当前正在加载的通道，加载spring查找文件时会用到该变量
                System.setProperty("canal.instance.destination", destination);
                this.beanFactory = getBeanFactory(springXml);
                String beanName = destination;
                if (!beanFactory.containsBean(beanName)) {
                    beanName = defaultName;
                }

                return (CanalInstance) beanFactory.getBean(beanName);
            } catch (Throwable e) {
                logger.error("generator instance failed.", e);

View on GitHub (pinned to 87be50e876)

Solutions

1. On the canal-manager web UI (or its backing DB), create an instance configuration for the exact destination name and ensure it is enabled.
2. Verify canal.manager.canalAddress / canal.manager address and credentials in canal.properties so findInstance queries the right server.
3. Confirm the destination passed to the canal deployer matches the instance name in the manager (case-sensitive).
4. 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.
5. 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.

Example fix

# before — manager mode, destination not registered
canal.instance.global.mode = manager
# canal.deployer started with -destination=order_db
# (no 'order_db' record on canal-manager)

# after — either register the instance on the manager, or switch to file mode
canal.instance.global.mode = file
# conf/order_db/instance.properties created

// In manager mode, confirm the destination is registered before starting the deployer
PlainCanal canal = canalConfigClient.findInstance(destination, null);
if (canal == null) {
    throw new IllegalStateException(
        "destination '" + destination + "' is not registered on canal-manager at " + managerAddress);
}

try {
    generator.generate(destination);
} catch (CanalException e) {
    if (e.getMessage() != null && e.getMessage().contains("config is not found")) {
        log.error("destination {} not found on manager {}; create it or switch to file mode",
            destination, managerAddress);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Pulsar Consumer subscriptName required
• init alarmHandlerPluginDir [%s] alarm handler [%s] error: %s
• Parse sql error
• ERROR # The kafka kerberos configuration file does not exist
• Subscript pulsar consumer error

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