alibaba/COLA · error · ExtensionException

EXTENSION_ILLEGAL

EXTENSION_ILLEGAL

Error message

Please assign a extension point interface for ${targetClz}

What it means

Thrown by ExtensionRegister.calculateExtensionPoint when an @Extension-annotated class implements no interfaces at all. The extension mechanism dispatches via an extension point interface, so a class with no interface cannot be registered. ExtensionException carries code EXTENSION_ILLEGAL.

Source

Thrown at cola-components/cola-component-extension-starter/src/main/java/com/alibaba/cola/extension/register/ExtensionRegister.java:95

                    ExtensionCoordinate extensionCoordinate = new ExtensionCoordinate(calculateExtensionPoint(extensionClz), bizScenario.getUniqueIdentity());
                    ExtensionPointI preVal = extensionRepository.getExtensionRepo().put(extensionCoordinate, extensionObject);
                    if (preVal != null) {
                        String errMessage = "Duplicate registration is not allowed for :" + extensionCoordinate;
                        throw new ExtensionException(EXTENSION_DEFINE_DUPLICATE, errMessage);
                    }
                }
            }
        }
    }

    /**
     * @param targetClz
     * @return
     */
    private String calculateExtensionPoint(Class<?> targetClz) {
        Class<?>[] interfaces = ClassUtils.getAllInterfacesForClass(targetClz);
        if (interfaces == null || interfaces.length == 0) {
            throw new ExtensionException(EXTENSION_ILLEGAL, "Please assign a extension point interface for " + targetClz);
        }
        for (Class intf : interfaces) {
            String extensionPoint = intf.getSimpleName();
            if (extensionPoint.contains(EXTENSION_EXTPT_NAMING)) {
                return intf.getName();
            }
        }
        String errMessage = "Your name of ExtensionPoint for " + targetClz +
                " is not valid, must be end of " + EXTENSION_EXTPT_NAMING;
        throw new ExtensionException(EXTENSION_INTERFACE_NAME_ILLEGAL, errMessage);
    }

}

View on GitHub (pinned to 352e1a8675)

Solutions

Make the @Extension class implement an extension point interface whose simple name contains 'ExtPt' (e.g. SomeBizExtPt)
Remove the @Extension annotation if the class is not meant to be an extension
Check for refactoring that dropped the 'implements' clause and restore it

Example fix

// before
@Extension(bizId = "pay")
public class AlipayExt {
    public void pay() {...}
}
// after
@Extension(bizId = "pay")
public class AlipayExt implements PayExtPt {
    public void pay() {...}
}

Defensive patterns

Strategy: validation

Validate before calling

if (ClassUtils.getAllInterfacesForClass(clazz) == null || ClassUtils.getAllInterfacesForClass(clazz).length == 0) {
    throw new IllegalStateException(clazz + " must implement an extension point interface");
}

Type guard

boolean isRegisterable(Class<?> clz) {
    Class<?>[] ifaces = ClassUtils.getAllInterfacesForClass(clz);
    return ifaces != null && ifaces.length > 0;
}

Try / catch

try {
    register(extension);
} catch (ExtensionException e) {
    if ("EXTENSION_ILLEGAL".equals(e.getErrorCode())) {
        log.error("{} is missing an extension point interface", extension.getClass(), e);
    }
}

Prevention

Always pair @Extension with an ExtPt interface
Add an architecture/unit test scanning @Extension classes for implemented interfaces
Review 'implements' clauses during refactors of extension classes

When it happens

Trigger: Registering an @Extension class (via extensionCoordinate registration) whose class implements zero interfaces, so ClassUtils.getAllInterfacesForClass returns null or empty.

Common situations: Annotating a concrete helper class with @Extension by mistake; refactoring removed the implemented interface; copying an @Extension annotation onto a non-extension class.

Related errors

AI-assisted analysis of alibaba/COLA@352e1a8675 (2026-09-08). Data as JSON: /api/errors/b8cd63ea3a4ab90d. Report an issue: GitHub.