alibaba/COLA · error · RuntimeException

Component ${targetClz} can not be found in Spring Container

Error message

Component ${targetClz} can not be found in Spring Container

What it means

The cola-component-domain-starter ApplicationContextHelper provides static access to Spring beans. getBean(Class) tries a by-type lookup then a de-capitalized simple-name lookup; if neither resolves a bean, it throws this RuntimeException, indicating the requested component is absent from the Spring context.

Source

Thrown at cola-components/cola-component-domain-starter/src/main/java/com/alibaba/cola/domain/ApplicationContextHelper.java:38

        ApplicationContextHelper.applicationContext = applicationContext;
    }

    public static <T> T getBean(Class<T> targetClz) {
        T beanInstance = null;
        //优先按type查
        try {
            beanInstance = (T)applicationContext.getBean(targetClz);
        } catch (Exception e) {
        }
        //按name查
        if (beanInstance == null) {
            String simpleName = targetClz.getSimpleName();
            //首字母小写
            simpleName = Character.toLowerCase(simpleName.charAt(0)) + simpleName.substring(1);
            beanInstance = (T)applicationContext.getBean(simpleName);
        }
        if (beanInstance == null) {
            throw new RuntimeException("Component " + targetClz + " can not be found in Spring Container");
        }
        return beanInstance;
    }

    public static Object getBean(String claz) {
        return ApplicationContextHelper.applicationContext.getBean(claz);
    }

    public static <T> T getBean(String name, Class<T> requiredType) {
        return ApplicationContextHelper.applicationContext.getBean(name, requiredType);
    }

    public static <T> T getBean(Class<T> requiredType, Object... params) {
        return ApplicationContextHelper.applicationContext.getBean(requiredType, params);
    }

    public static ApplicationContext getApplicationContext() {
        return applicationContext;

View on GitHub (pinned to 352e1a8675)

Solutions

1. Annotate the implementation class (@Component/@Service/@Repository) and ensure its package is component-scanned.
2. Confirm the registered bean name equals the de-capitalized simple class name, or look up by explicit name via getBean(String).
3. Verify the Spring context is fully started and ApplicationContextHelper has received the ApplicationContext (ApplicationContextAware wiring).
4. In tests, use a Spring test context rather than calling the static helper bare.

Example fix

// before
OrderGateway gw = ApplicationContextHelper.getBean(OrderGatewayImpl.class); // throws
// after
@Repository // register the implementation
public class OrderGatewayImpl implements OrderGateway { ... }
OrderGateway gw = ApplicationContextHelper.getBean(OrderGateway.class);

ApplicationContext ctx = ApplicationContextHelper.getApplicationContext();
if (ctx == null || ctx.getBeanNamesForType(OrderGateway.class).length == 0) {
    throw new IllegalStateException("OrderGateway is not registered in the Spring container");
}

public static <T> boolean beanExists(ApplicationContext ctx, Class<T> clz) {
    return ctx != null && ctx.getBeanNamesForType(clz).length > 0;
}

try {
    OrderGateway gw = ApplicationContextHelper.getBean(OrderGateway.class);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("can not be found in Spring Container")) {
        // register/fall back to a default implementation
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling ApplicationContextHelper.getBean(SomeGateway.class) when the implementation class isn't a registered Spring bean (missing annotation or outside component scan), or when applicationContext hasn't been injected (helper used outside a running Spring context).

Common situations: Domain code fetching a Gateway/Repository implementation that was never annotated @Repository; using the helper in non-Spring unit tests; bean defined with a custom name mismatching the conventional lookup; premature use during context startup.

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

• Component ${targetClz} can not be found in Spring Container
• 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/dbd6ae510216b7cf. Report an issue: GitHub.