apache/shenyu · error · IllegalStateException

No implementation defined in /META-INF/services/

Error message

No implementation defined in /META-INF/services/%s, please check whether the file exists and has the right implementation class!

What it means

SpiLoadFactory.loadFirst uses java.util.ServiceLoader to load implementations declared in META-INF/services/<interface>. If no implementation is registered (empty iterator) it throws IllegalStateException stating that the services file is missing or contains no valid implementation class.

Solutions

1. Create META-INF/services/<interface FQCN> containing the implementation class name.
2. Verify the implementation class name/package is correct and the class has a no-arg constructor.
3. Fix shade plugin config to append ServicesResourceTransformer so service files merge instead of being overwritten.
4. Add the module containing the implementation to the classpath.

Example fix

// missing file -> add:
// src/main/resources/META-INF/services/org.apache.shenyu.spi.SpiInterface
// after: contents
org.apache.shenyu.example.MySpiImplementation

ClassLoader cl = clazz.getClassLoader();
if (cl.getResource("META-INF/services/" + clazz.getName()) == null) {
    throw new IllegalStateException("missing service file for " + clazz.getName());
}

try { S impl = SpiLoadFactory.loadFirst(Api.class); } catch (IllegalStateException e) { LOG.error("SPI impl missing", e); useDefaultImplementation(); }

When it happens

Trigger: Calling SpiLoadFactory.loadFirst(SomeApi.class) when META-INF/services/<fully.qualified.Interface> is absent from the classpath, or exists but lists classes that cannot be instantiated (so ServiceLoader yields nothing usable).

Common situations: Shaded/fat JAR dropped META-INF/services entries during merging; forgot the @Join/registration file for the SPI implementation; wrong class name or package after refactoring; test classpath missing the implementation module.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• load extension resources error
• load extension resources error,Duplicate class clazz name…
• If the preMatch method was implemented ,the preParse method…
• Can't find wasm file
• extension clazz (clazz) is not interface!

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

Appendix: source

Thrown at shenyu-common/src/main/java/org/apache/shenyu/common/utils/SpiLoadFactory.java:39

import java.util.ServiceLoader;

/**
 * SpiLoadFactory.
 */
public class SpiLoadFactory {

    /**
     * Load first s.
     *
     * @param <S>   the type parameter
     * @param clazz the clazz
     * @return the s
     */
    public static <S> S loadFirst(final Class<S> clazz) {
        final ServiceLoader<S> loader = loadAll(clazz);
        final Iterator<S> iterator = loader.iterator();
        if (!iterator.hasNext()) {
            throw new IllegalStateException(String.format(
                    "No implementation defined in /META-INF/services/%s, please check whether the file exists and has the right implementation class!",
                    clazz.getName()));
        }
        return iterator.next();
    }

    /**
     * Load all service loader.
     *
     * @param <S>   the type parameter
     * @param clazz the clazz
     * @return the service loader
     */
    public static <S> ServiceLoader<S> loadAll(final Class<S> clazz) {
        return ServiceLoader.load(clazz);
    }
}

View on GitHub (pinned to 567142e072)