apache/shenyu · error · IllegalArgumentException

name is error

Error message

 name is error

What it means

getJoin(name) throws IllegalArgumentException when the given name does not match any @Join-annotated implementation registered under the SPI interface's META-INF/shenyu/ resource. The name lookup in the extension class map returned null, so the name is unknown to the loader.

Solutions

1. Check the exact name registered in META-INF/shenyu/<interface-fqcn>
2. Ensure the jar containing the implementation and resource file is on the classpath
3. Use getDefaultJoin() or a validated whitelist of names
4. Add the implementation with @Join(name = "nameX") if it is your own class

Example fix

// before
LoadBalance lb = ExtensionLoader.getExtensionLoader(LoadBalance.class).getJoin("roundrobin");
// after
// META-INF/shenyu/... registers "roundRobin" — fix the name
LoadBalance lb = ExtensionLoader.getExtensionLoader(LoadBalance.class).getJoin("roundRobin");

// verify registration before lookup
java.net.URL res = getClass().getClassLoader().getResource("META-INF/shenyu/" + LoadBalance.class.getName());
// then confirm the configured name appears in that file

try { return loader.getJoin(name); } catch (IllegalArgumentException e) { log.error("Unknown extension name '{}': {}", name, e.getMessage()); return loader.getDefaultJoin(); }

When it happens

Trigger: Calling loader.getJoin("nameX") where nameX is not a key in the interface's META-INF/shenyu/<InterfaceFQN> file.

Common situations: Typo in configured extension name; implementation jar not on the classpath so its resource file is missing; config value naming an extension from a different project; renamed implementation without updating config.

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

• load extension resources error
• load extension resources error,Duplicate class clazz name…
• shenyu.jwt.secretKey is not configured. In a multi-instance…
• shenyu discovery mode current didn't support
• websocket on client open failed, namespaceId is null

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

Appendix: source

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

        if (StringUtils.isBlank(cachedDefaultName)) {
            return null;
        }
        return getJoin(cachedDefaultName);
    }
    
    /**
     * Gets join.
     *
     * @param name the name
     * @return the join.
     */
    public T getJoin(final String name) {
        if (StringUtils.isBlank(name)) {
            throw new NullPointerException("get join name is null");
        }
        ClassEntity classEntity = getExtensionClassesEntity().get(name);
        if (Objects.isNull(classEntity)) {
            throw new IllegalArgumentException(name + " name is error");
        }
        if (!classEntity.isSingleton()) {
            return (T) createExtension(classEntity);
        }
        Holder<Object> objectHolder = cachedInstances.get(name);
        if (Objects.isNull(objectHolder)) {
            cachedInstances.putIfAbsent(name, new Holder<>());
            objectHolder = cachedInstances.get(name);
        }
        Object value = objectHolder.getValue();
        if (Objects.isNull(value)) {
            synchronized (objectHolder) {
                value = objectHolder.getValue();
                if (Objects.isNull(value)) {
                    createExtension(name, objectHolder);
                    value = objectHolder.getValue();
                }
            }

View on GitHub (pinned to 567142e072)