alibaba/canal · error · IllegalArgumentException

Canal prometheus collector need to implement InstanceRegistr

Error message

Canal prometheus collector need to implement InstanceRegistry.

What it means

CanalInstanceExports instruments instances through several Prometheus collectors and requires each collector to implement InstanceRegistry so it can register/unregister per-instance metrics. requiredInstanceGuard() type-checks each collector and throws IllegalArgumentException if one is missing the InstanceRegistry interface. This is an internal API-contract violation, not a user config problem.

Source

Thrown at prometheus/src/main/java/com/alibaba/otter/canal/prometheus/CanalInstanceExports.java:80

        requiredInstanceRegistry(entryCollector).register(instance);
        requiredInstanceRegistry(metaCollector).register(instance);
        requiredInstanceRegistry(sinkCollector).register(instance);
        requiredInstanceRegistry(parserCollector).register(instance);
        logger.info("Successfully register metrics for instance {}.", instance.getDestination());
    }

    void unregister(CanalInstance instance) {
        requiredInstanceRegistry(storeCollector).unregister(instance);
        requiredInstanceRegistry(entryCollector).unregister(instance);
        requiredInstanceRegistry(metaCollector).unregister(instance);
        requiredInstanceRegistry(sinkCollector).unregister(instance);
        requiredInstanceRegistry(parserCollector).unregister(instance);
        logger.info("Successfully unregister metrics for instance {}.", instance.getDestination());
    }

    private InstanceRegistry requiredInstanceRegistry(Collector collector) {
        if (!(collector instanceof InstanceRegistry)) {
            throw new IllegalArgumentException("Canal prometheus collector need to implement InstanceRegistry.");
        }
        return (InstanceRegistry) collector;
    }

}

View on GitHub (pinned to 87be50e876)

Solutions

1. Ensure all five collectors passed to CanalInstanceExports are the canonical impl classes (StoreCollector, EntryCollector, MetaCollector, etc.) that implement InstanceRegistry.
2. Align the prometheus module version with the rest of the canal deployment (rebuild from the same source tree).
3. If providing a custom collector, implement com.alibaba.otter.canal.prometheus.InstanceRegistry on it.

Example fix

// before
// a custom Collector passed into CanalInstanceExports

// after
public class MyCollector extends Collector implements InstanceRegistry {
    public void register(CanalInstance i) { ... }
    public void unregister(CanalInstance i) { ... }
}

private static void requireInstanceRegistry(Collector c) {
    if (!(c instanceof InstanceRegistry)) {
        throw new IllegalStateException(c.getClass() + " must implement InstanceRegistry");
    }
}
// call for all five collectors before CanalInstanceExports is used

boolean isInstanceRegistryCollector(Collector c) {
    return c instanceof Collector && c instanceof InstanceRegistry;
}

try {
    exports.unregister(instance);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("InstanceRegistry")) {
        logger.error("Collector version mismatch; realign prometheus module", e);
    }
    throw e;
}

When it happens

Trigger: Registering/unregistering an instance when one of the wired collectors (storeCollector, entryCollector, metaCollector, sinkCollector, parserCollector) is a Collector that does not implement InstanceRegistry. Happens when a custom/older collector is substituted into CanalInstanceExports, or after a version mismatch where a collector class was replaced.

Common situations: Custom prometheus module that supplies its own collector not implementing InstanceRegistry; running a prometheus jar from a different canal version than the rest of the deployer; partial classpath that loads a stub collector.

Related errors

• CanalEventSink must be EntryEventSink
• No kudu adapter found for config key: {}
• not allow to change outAdapterKey
• KuduMapping.database
• ERROR load Config: {} {}

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