{"record":{"id":"50d75e47b2d3b584","repo":"github/copilot-sdk","slug":"native-runtime-metadata-not-found-on-classpath","errorCode":null,"errorMessage":"Native runtime metadata not found on classpath:  — add the matching classifier JAR to the classpath","messagePattern":"Native runtime metadata 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":271,"sourceCode":"                    + \" — ensure Maven resource filtering has run (mvn process-resources)\");\n        }\n        Properties props = new Properties();\n        try (InputStream in = resource.openStream()) {\n            props.load(in);\n        }\n        String version = props.getProperty(\"version\");\n        if (version == null || version.isBlank()) {\n            throw new IllegalStateException(\"Blank or missing 'version' property in \" + VERSION_RESOURCE\n                    + \" — check Maven resource filtering configuration\");\n        }\n        return version;\n    }\n\n    private static String readNativePackageVersion(ClassLoader loader, String classifier) throws IOException {\n        String resourcePath = \"native/\" + classifier + \"/\" + PLATFORM_PROPERTIES_FILENAME;\n        URL resource = loader.getResource(resourcePath);\n        if (resource == null) {\n            throw new FileNotFoundException(\"Native runtime metadata not found on classpath: \" + resourcePath\n                    + \" — add the matching classifier JAR to the classpath\");\n        }\n\n        Properties props = new Properties();\n        try (InputStream in = resource.openStream()) {\n            props.load(in);\n        }\n        String version = props.getProperty(\"version\");\n        if (version == null || version.isBlank()) {\n            throw new IllegalStateException(\"Blank or missing 'version' property in \" + resourcePath);\n        }\n        return version;\n    }\n\n    /**\n     * Resolves the runtime binary path using the given parameters. Package-private\n     * to allow injection of test doubles in unit tests.\n     */","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/NativeRuntimeLoader.java#L253-L289","documentation":"readNativePackageVersion() could not find native/<classifier>/platform.properties on the classpath. This metadata file, shipped in the platform classifier JAR, records the native package version used in the cache path; without it the native runtime version cannot be determined.","triggerScenarios":"Calling NativeRuntimeLoader.resolve() (via nativeVersion/extraction) when the classifier JAR for the detected platform is absent, or an older classifier JAR lacking platform.properties.","commonSituations":"Missing native classifier Maven dependency; running on an unmapped OS/arch; fat-JAR filtering that dropped native/ resources; SDK version upgraded while the classifier JAR stayed old (file added in newer releases).","solutions":["Add the native classifier dependency matching the running platform at the SDK's version.","Check the JAR contains the metadata: jar tf copilot-sdk-native-*.jar | grep platform.properties.","Log/verify PlatformDetector.detectClassifier() output and ensure a JAR exists for that classifier.","Fix packaging filters that exclude native/** resources from the assembled artifact."],"exampleFix":"// before (pom.xml): no native artifact for the platform\n// after\n<dependency>\n  <groupId>com.github.copilot</groupId>\n  <artifactId>copilot-sdk-native</artifactId>\n  <version>1.2.0</version>\n  <classifier>darwin-arm64</classifier>\n</dependency>","handlingStrategy":"validation","validationCode":"String classifier = detectClassifier();\nboolean metaPresent = getClass().getResourceAsStream(\"/native/\" + classifier + \"/platform.properties\") != null;\nif (!metaPresent) throw new IllegalStateException(\"Classifier JAR for \" + classifier + \" missing platform.properties — add native dependency\");\n","typeGuard":null,"tryCatchPattern":"try {\n    Path runtime = NativeRuntimeLoader.resolve();\n} catch (FileNotFoundException e) {\n    if (e.getMessage().contains(\"platform.properties\")) {\n        throw new IllegalStateException(\"Native classifier JAR missing on classpath for this platform\", e);\n    } else throw e;\n}","preventionTips":["Ship all platform classifier JARs (or use a classifier profile matching the target OS/arch).","Keep native artifact and SDK versions in lockstep.","Confirm platform.properties exists inside the classifier JAR before release.","Test resolution inside the actual deployment image/container."],"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"}