{"record":{"id":"d57ec456f405271f","repo":"apache/shenyu","slug":"no-implementation-defined-in-meta-inf-services-s-please","errorCode":null,"errorMessage":"No implementation defined in /META-INF/services/%s, please check whether the file exists and has the right implementation class!","messagePattern":"No implementation defined in /META-INF/services/(.+?), please check whether the file exists and has the right implementation class!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"shenyu-common/src/main/java/org/apache/shenyu/common/utils/SpiLoadFactory.java","lineNumber":39,"sourceCode":"import java.util.ServiceLoader;\n\n/**\n * SpiLoadFactory.\n */\npublic class SpiLoadFactory {\n\n    /**\n     * Load first s.\n     *\n     * @param <S>   the type parameter\n     * @param clazz the clazz\n     * @return the s\n     */\n    public static <S> S loadFirst(final Class<S> clazz) {\n        final ServiceLoader<S> loader = loadAll(clazz);\n        final Iterator<S> iterator = loader.iterator();\n        if (!iterator.hasNext()) {\n            throw new IllegalStateException(String.format(\n                    \"No implementation defined in /META-INF/services/%s, please check whether the file exists and has the right implementation class!\",\n                    clazz.getName()));\n        }\n        return iterator.next();\n    }\n\n    /**\n     * Load all service loader.\n     *\n     * @param <S>   the type parameter\n     * @param clazz the clazz\n     * @return the service loader\n     */\n    public static <S> ServiceLoader<S> loadAll(final Class<S> clazz) {\n        return ServiceLoader.load(clazz);\n    }\n}\n","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-common/src/main/java/org/apache/shenyu/common/utils/SpiLoadFactory.java#L21-L57","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Create META-INF/services/<interface FQCN> containing the implementation class name.","Verify the implementation class name/package is correct and the class has a no-arg constructor.","Fix shade plugin config to append ServicesResourceTransformer so service files merge instead of being overwritten.","Add the module containing the implementation to the classpath."],"exampleFix":"// missing file -> add:\n// src/main/resources/META-INF/services/org.apache.shenyu.spi.SpiInterface\n// after: contents\norg.apache.shenyu.example.MySpiImplementation","handlingStrategy":"try-catch","validationCode":"ClassLoader cl = clazz.getClassLoader();\nif (cl.getResource(\"META-INF/services/\" + clazz.getName()) == null) {\n    throw new IllegalStateException(\"missing service file for \" + clazz.getName());\n}","typeGuard":null,"tryCatchPattern":"try { S impl = SpiLoadFactory.loadFirst(Api.class); } catch (IllegalStateException e) { LOG.error(\"SPI impl missing\", e); useDefaultImplementation(); }","preventionTips":["Always ship META-INF/services/<interface> with the implementation class","Configure ServicesResourceTransformer in shade plugin for fat JARs","Verify SPI files survive packaging in CI","Use loadAll + isEmpty checks when implementations are optional"],"tags":["spi","serviceloader","classpath","meta-inf"],"backgroundTag":"missing-dependency","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}