{"record":{"id":"a688372febc03172","repo":"github/copilot-sdk","slug":"runtime-wrapper-not-found-on-classpath-add-the","errorCode":null,"errorMessage":"Runtime wrapper not found on classpath:  — add the matching classifier JAR to the classpath","messagePattern":"Runtime wrapper not found on classpath:  — add the matching classifier JAR to the classpath","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/ffi/NativeRuntimeLoader.java","lineNumber":202,"sourceCode":"        return resolveRuntimeWrapper(defaultCacheBase(), loader, classifier, version);\n    }\n\n    static Path resolveRuntimeWrapper(Path cacheBase, ClassLoader loader, String classifier, String version)\n            throws IOException {\n        Path runtimePath = extractRuntimeToCache(cacheBase, loader, classifier, version, DEFAULT_PUBLISHER, false);\n        Path cacheDir = runtimePath.getParent();\n        String wrapperName = classifier.startsWith(\"win32-\")\n                ? RUNTIME_WRAPPER_FILENAME_WINDOWS\n                : RUNTIME_WRAPPER_FILENAME;\n        Path cachedWrapper = cacheDir.resolve(wrapperName);\n        if (isValidCachedCli(cachedWrapper)) {\n            return cachedWrapper;\n        }\n\n        String resourcePath = \"native/\" + classifier + \"/\" + wrapperName;\n        URL resource = loader.getResource(resourcePath);\n        if (resource == null) {\n            throw new FileNotFoundException(\"Runtime wrapper not found on classpath: \" + resourcePath\n                    + \" — add the matching classifier JAR to the classpath\");\n        }\n\n        Path temp = Files.createTempFile(cacheDir, \"runtime-wrapper-tmp-\", \"\");\n        try {\n            copyResourceToTemp(resource, resourcePath, temp);\n            makeExecutable(temp);\n            DEFAULT_PUBLISHER.publish(temp, cachedWrapper);\n        } finally {\n            tryDelete(temp);\n        }\n        if (!isValidCachedCli(cachedWrapper)) {\n            throw new IOException(\"Published runtime wrapper is not a non-empty executable file: \" + cachedWrapper);\n        }\n        return cachedWrapper;\n    }\n\n    static Path resolveEntrypoint(String configuredCli, Path runtimePath) throws IOException {","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/NativeRuntimeLoader.java#L184-L220","documentation":"resolveRuntimeWrapper() could not find the classpath resource native/<classifier>/copilot-runtime (or copilot-runtime.exe on Windows). The runtime wrapper executable ships in a platform-specific classifier JAR; without it on the classpath the out-of-process runtime cannot be launched.","triggerScenarios":"Calling NativeRuntimeLoader.resolveRuntimeWrapper() when the classifier JAR for the detected platform (e.g. copilot-sdk-native-linux-x64) is not a dependency, or an older classifier JAR predating the wrapper artifact.","commonSituations":"Adding the SDK but forgetting the native classifier dependency; running on an OS/arch with no published classifier JAR; a fat JAR/shading build that excluded native/<classifier>/ resources; upgrading the SDK without upgrading the classifier JAR (wrapper filename added later).","solutions":["Add the Maven dependency for the classifier matching the running platform (e.g. <classifier>linux-x64</classifier> native artifact) at the same version as the SDK.","Verify the JAR contains native/<classifier>/copilot-runtime: jar tf copilot-sdk-native-*.jar | grep copilot-runtime.","Check build/shading config (maven-shade-plugin filters, spring-boot layers) isn't excluding native/ resources.","Confirm PlatformDetector.detectClassifier() resolves to a platform you have a JAR for."],"exampleFix":"// before (pom.xml): only SDK jar\n<dependency>\n  <groupId>com.github.copilot</groupId>\n  <artifactId>copilot-sdk</artifactId>\n  <version>1.2.0</version>\n</dependency>\n\n// after: add matching native classifier JAR\n<dependency>\n  <groupId>com.github.copilot</groupId>\n  <artifactId>copilot-sdk-native</artifactId>\n  <version>1.2.0</version>\n  <classifier>linux-x64</classifier>\n</dependency>","handlingStrategy":"validation","validationCode":"String classifier = detectClassifier(); // e.g. linux-x64\nboolean wrapperPresent = getClass().getResourceAsStream(\"/native/\" + classifier + \"/copilot-runtime\") != null;\nif (!wrapperPresent) throw new IllegalStateException(\"Classifier JAR missing runtime wrapper for \" + classifier);\n","typeGuard":null,"tryCatchPattern":"try {\n    Path wrapper = NativeRuntimeLoader.resolveRuntimeWrapper();\n} catch (FileNotFoundException e) {\n    // fail fast with actionable message pointing at the classifier dependency\n    throw new IllegalStateException(\"Add copilot-sdk-native classifier JAR to the classpath\", e);\n}","preventionTips":["Always add the native classifier JAR dependency at the same version as the SDK.","Smoke-test in a clean container that resolution succeeds before deploying.","Audit shade/packaging filters so native/** resources are never excluded.","Pin SDK and native artifact versions together (BOM or common parent)."],"tags":["classpath","native-loader","missing-dependency","maven"],"backgroundTag":"resource-not-found","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}