alibaba/canal · error · IllegalArgumentException

Extension type({}) is not interface!

Error message

Extension type({}) is not interface!

What it means

Thrown by ExtensionLoader.getExtensionLoader when the supplied type is not a Java interface. Canal's SPI mechanism (Dubbo-style) only loads extensions for interfaces; passing a concrete class or enum is rejected because the whole point of SPI is to bind implementations to an abstraction.

Source

Thrown at connector/core/src/main/java/com/alibaba/otter/canal/connector/core/spi/ExtensionLoader.java:74

    private final ConcurrentMap<String, Holder<Object>>              cachedInstances            = new ConcurrentHashMap<>();

    private String                                                   cachedDefaultName;

    private ConcurrentHashMap<String, IllegalStateException>         exceptions                 = new ConcurrentHashMap<>();

    private static <T> boolean withExtensionAnnotation(Class<T> type) {
        return type.isAnnotationPresent(SPI.class);
    }

    public static <T> ExtensionLoader<T> getExtensionLoader(Class<T> type) {
        return getExtensionLoader(type, DEFAULT_CLASSLOADER_POLICY);
    }

    @SuppressWarnings("unchecked")
    public static <T> ExtensionLoader<T> getExtensionLoader(Class<T> type, String classLoaderPolicy) {
        if (type == null) throw new IllegalArgumentException("Extension type == null");
        if (!type.isInterface()) {
            throw new IllegalArgumentException("Extension type(" + type + ") is not interface!");
        }
        if (!withExtensionAnnotation(type)) {
            throw new IllegalArgumentException("Extension type(" + type + ") is not extension, because WITHOUT @"
                                               + SPI.class.getSimpleName() + " Annotation!");
        }

        ExtensionLoader<T> loader = (ExtensionLoader<T>) EXTENSION_LOADERS.get(type);
        if (loader == null) {
            EXTENSION_LOADERS.putIfAbsent(type, new ExtensionLoader<T>(type, classLoaderPolicy));
            loader = (ExtensionLoader<T>) EXTENSION_LOADERS.get(type);
        }
        return loader;
    }

    public ExtensionLoader(Class<?> type){
        this.type = type;
        this.classLoaderPolicy = DEFAULT_CLASSLOADER_POLICY;
    }

View on GitHub (pinned to 87be50e876)

Solutions

1. Pass the extension interface (the one annotated @SPI), not an implementation class.
2. Verify the class literal in the getExtensionLoader call is an interface via reflection if unsure.

Example fix

// before
ExtensionLoader.getExtensionLoader(RocketMQProducer.class);  // impl
// after
ExtensionLoader.getExtensionLoader(CanalMQProducer.class);    // @SPI interface

// Guard: require an interface
if (type == null || !type.isInterface()) {
    throw new IllegalArgumentException(type + " is not an extension interface");
}

boolean isSpiInterface(Class<?> type) {
    return type != null && type.isInterface()
        && type.isAnnotationPresent(
            com.alibaba.otter.canal.connector.core.spi.SPI.class);
}

When it happens

Trigger: Calling getExtensionLoader(SomeImpl.class) where SomeImpl is a class rather than an interface; passing an enum or annotation type.

Common situations: Developer mistakenly passes the implementation class instead of the extension interface; refactor renamed the interface and the call site was not updated.

Related errors

• Extension type == null
• Extension type({}) is not extension, because WITHOUT @{} Ann
• Extension name == null
• Extension instance(name: {}, class: {}) could not be instan
• Extension instance(name: {}, class: {}) could not be instan

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