alibaba/canal · error · IllegalStateException

Extension instance(name: {}, class: {}) could not be instan

Error message

Extension instance(name: {}, class: {})  could not be instantiated: class could not be found

What it means

Error "Extension instance(name: {}, class: {}) could not be instantiated: class could not be found" thrown in alibaba/canal.

Source

Thrown at client-adapter/common/src/main/java/com/alibaba/otter/canal/client/adapter/support/ExtensionLoader.java:166

        return (T) instance;
    }

    /**
     * 返回缺省的扩展，如果没有设置则返回<code>null</code>
     */
    public T getDefaultExtension() {
        getExtensionClasses();
        if (null == cachedDefaultName || cachedDefaultName.length() == 0 || "true".equals(cachedDefaultName)) {
            return null;
        }
        return getExtension(cachedDefaultName);
    }

    @SuppressWarnings("unchecked")
    private T createExtension(String name) {
        Class<?> clazz = getExtensionClasses().get(name);
        if (clazz == null) {
            throw new IllegalStateException("Extension instance(name: " + name + ", class: " + type
                                            + ")  could not be instantiated: class could not be found");
        }
        try {
            T instance = (T) EXTENSION_INSTANCES.get(clazz);
            if (instance == null) {
                EXTENSION_INSTANCES.putIfAbsent(clazz, (T) clazz.newInstance());
                instance = (T) EXTENSION_INSTANCES.get(clazz);
            }
            return instance;
        } catch (Throwable t) {
            throw new IllegalStateException("Extension instance(name: " + name + ", class: " + type
                                            + ")  could not be instantiated: " + t.getMessage(),
                t);
        }
    }

    @SuppressWarnings("unchecked")
    private T createExtension(String name, String key) {

View on GitHub (pinned to 87be50e876)

Solutions

1. Ensure the extension implementation class is on the classpath (adapter jar included in the lib/plugin directory).
2. Check META-INF/canal SPI resource files reference the correct fully-qualified class name.

When it happens

Trigger: Thrown at client-adapter/common/src/main/java/com/alibaba/otter/canal/client/adapter/support/ExtensionLoader.java:166 when the library encounters an invalid state.

Common situations: Extension class not found on the classpath. Verify the plugin jar is deployed and the class name in the SPI file matches exactly; class-not-found at load time should list the searched locations.

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