alibaba/COLA · error · ExtensionException

EXTENSION_NOT_FOUND

EXTENSION_NOT_FOUND

Error message

Can not find extension with ExtensionPoint: ${targetClz} BizScenario:${bizScenario.getUniqueIdentity()}

What it means

ExtensionExecutor.locateExtension looks up an ExtensionPointI implementation in the extension repository for a given ExtensionCoordinate (extension point class + BizScenario unique identity). When no extension is registered under that coordinate, it throws ExtensionException with code EXTENSION_NOT_FOUND. COLA's extension component routes behavior by business identity, so this error means no implementation was registered for the requested (ExtensionPoint, BizScenario) combination.

Source

Thrown at cola-components/cola-component-extension-starter/src/main/java/com/alibaba/cola/extension/ExtensionExecutor.java:77

        if (extension != null) {
            return extension;
        }

        // second try with default scenario
        extension = secondTry(targetClz, bizScenario);
        if (extension != null) {
            return extension;
        }

        // third try with default use case + default scenario
        extension = defaultUseCaseTry(targetClz, bizScenario);
        if (extension != null) {
            return extension;
        }

        String errMessage = "Can not find extension with ExtensionPoint: " +
                targetClz + " BizScenario:" + bizScenario.getUniqueIdentity();
        throw new ExtensionException(EXTENSION_NOT_FOUND, errMessage);
    }

    /**
     * first try with full namespace
     * <p>
     * example:  biz1.useCase1.scenario1
     */
    private <Ext> Ext firstTry(Class<Ext> targetClz, BizScenario bizScenario) {
        logger.debug("First trying with " + bizScenario.getUniqueIdentity());
        return locate(targetClz.getName(), bizScenario.getUniqueIdentity());
    }

    /**
     * second try with default scenario
     * <p>
     * example:  biz1.useCase1.#defaultScenario#
     */
    private <Ext> Ext secondTry(Class<Ext> targetClz, BizScenario bizScenario) {

View on GitHub (pinned to 352e1a8675)

Solutions

1. Check the BizScenario value against the @Extension annotation's bizId/useCase/scenario on the implementing class — they must match exactly.
2. Ensure the extension class is a Spring bean (@Component + @Extension) and is in a scanned package.
3. Add a default/fallback extension registered under BizScenario.DEFAULT for unmatched scenarios.
4. Log the requested unique identity and list registered coordinates at startup to spot mismatches.

Example fix

// before
BizScenario scenario = BizScenario.valueOf("biz1", "useCase1", "scenario");
// after  (must match the @Extension annotation exactly)
// @Extension(bizId = "biz1", useCase = "useCase1", scenario = "scenario")
BizScenario scenario = BizScenario.valueOf("biz1", "useCase1", "scenario");

if (extensionExecutor.locateExtension(ExtPt.class, bizScenario) == null) { /* use default scenario or error */ }

try { return extensionExecutor.execute(ExtPt.class, bizScenario, ...); } catch (ExtensionException e) { if ("EXTENSION_NOT_FOUND".equals(e.getErrCode())) { return defaultBehavior(); } throw e; }

When it happens

Trigger: Calling ExtensionExecutor.execute/responseCode/locateExtension (directly or via `extension(...)`) with an ExtensionPointI interface and a BizScenario whose unique identity (bizId.useCase.scenario) has no registered @Extension implementation, and no fallback matching.

Common situations: BizScenario constructed with a typo or different casing than the @Extension annotation's bizId/useCase/scenario; extension bean not scanned by Spring (missing component scan or the @Extension class not annotated @Component); requesting a scenario that was never configured.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• BizScenario can not be null for extension
• EXTENSION_DEFINE_DUPLICATE
• B_CUSTOMER_companyNameConflict
• ${companyName} has already existed, you can not add it
• B_CUSTOMER_companyNameConflict

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