apache/shenyu · error · IllegalStateException

Extension instance(name: name, class: clazz) could not be…

Error message

Extension instance(name: name, class: clazz)  could not be instantiated: message

What it means

createExtension instantiates the resolved implementation class via Class.newInstance(). This IllegalStateException wraps InstantiationException or IllegalAccessException when the class cannot be instantiated — typically because it has no accessible no-arg constructor, is abstract, or is an inner/non-static class.

Solutions

Give the implementation a public no-argument constructor
Make the class non-abstract and concrete
Move inner classes to static or top-level
Obtain dependencies inside the constructor or via setters after instantiation instead of via constructor params

Example fix

// before
public class RoundRobinLoadBalance {
    public RoundRobinLoadBalance(int modulo) { ... }
}
// after
public class RoundRobinLoadBalance {
    public RoundRobinLoadBalance() { this.modulo = 1; }
}

Defensive patterns

Strategy: try-catch

Validate before calling

try { clazz.getDeclaredConstructor(); } catch (NoSuchMethodException e) { throw new IllegalStateException(clazz + " lacks no-arg constructor"); }

Try / catch

try { return loader.getJoin(name); } catch (IllegalStateException e) { log.error("Cannot instantiate extension {}: {}", name, e.getCause(), e); throw e; }

Prevention

Give every @Join implementation a public no-arg constructor
Never register abstract or non-static inner classes
Avoid constructor-injected dependencies in SPI implementations

When it happens

Trigger: An @Join implementation registered in META-INF/shenyu/ that is abstract, has only parameterized constructors, is not public, or is a non-static inner class, is requested via getJoin.

Common situations: SPI implementations with constructor-injected dependencies (works with Spring but not ShenYu SPI); abstract base class accidentally registered; anonymous/local classes; constructors made non-public after a refactor.

Related errors

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/962099389e39f93f. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-spi/src/main/java/org/apache/shenyu/spi/ExtensionLoader.java:202

                    }).collect(Collectors.toList());
        }
        List<T> joins = new ArrayList<>();
        List<ClassEntity> classEntities = extensionClassesEntity.values().stream()
                .sorted(CLASS_ENTITY_COMPARATOR).collect(Collectors.toList());
        classEntities.forEach(v -> {
            T join = this.getJoin(v.getName());
            joins.add(join);
        });
        return joins;
    }

    @SuppressWarnings("unchecked")
    private Object createExtension(final ClassEntity classEntity) {
        Class<?> aClass = classEntity.getClazz();
        try {
            return aClass.newInstance();
        } catch (InstantiationException | IllegalAccessException e) {
            throw new IllegalStateException("Extension instance(name: " + classEntity.getName() + ", class: "
                    + aClass + ")  could not be instantiated: " + e.getMessage(), e);

        }
    }
    
    @SuppressWarnings("unchecked")
    private void createExtension(final String name, final Holder<Object> holder) {
        ClassEntity classEntity = getExtensionClassesEntity().get(name);
        if (Objects.isNull(classEntity)) {
            throw new IllegalArgumentException(name + " name is error");
        }
        Class<?> aClass = classEntity.getClazz();
        Object o = joinInstances.get(aClass);
        if (Objects.isNull(o)) {
            o = createExtension(classEntity);
            if (classEntity.isSingleton()) {
                joinInstances.putIfAbsent(aClass, o);
                o = joinInstances.get(aClass);

View on GitHub (pinned to 567142e072)