github/copilot-sdk · error · FileNotFoundException

Native runtime metadata not found on classpath: — add the…

Error message

Native runtime metadata not found on classpath:  — add the matching classifier JAR to the classpath

What it means

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.

Solutions

  1. Add the native classifier dependency matching the running platform at the SDK's version.
  2. Check the JAR contains the metadata: jar tf copilot-sdk-native-*.jar | grep platform.properties.
  3. Log/verify PlatformDetector.detectClassifier() output and ensure a JAR exists for that classifier.
  4. Fix packaging filters that exclude native/** resources from the assembled artifact.

Example fix

// before (pom.xml): no native artifact for the platform
// after
<dependency>
  <groupId>com.github.copilot</groupId>
  <artifactId>copilot-sdk-native</artifactId>
  <version>1.2.0</version>
  <classifier>darwin-arm64</classifier>
</dependency>
Defensive patterns

Strategy: validation

Validate before calling

String classifier = detectClassifier();
boolean metaPresent = getClass().getResourceAsStream("/native/" + classifier + "/platform.properties") != null;
if (!metaPresent) throw new IllegalStateException("Classifier JAR for " + classifier + " missing platform.properties — add native dependency");

Try / catch

try {
    Path runtime = NativeRuntimeLoader.resolve();
} catch (FileNotFoundException e) {
    if (e.getMessage().contains("platform.properties")) {
        throw new IllegalStateException("Native classifier JAR missing on classpath for this platform", e);
    } else throw e;
}

Prevention

When it happens

Trigger: Calling NativeRuntimeLoader.resolve() (via nativeVersion/extraction) when the classifier JAR for the detected platform is absent, or an older classifier JAR lacking platform.properties.

Common situations: 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).

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

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/50d75e47b2d3b584. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/NativeRuntimeLoader.java:271

                    + " — ensure Maven resource filtering has run (mvn process-resources)");
        }
        Properties props = new Properties();
        try (InputStream in = resource.openStream()) {
            props.load(in);
        }
        String version = props.getProperty("version");
        if (version == null || version.isBlank()) {
            throw new IllegalStateException("Blank or missing 'version' property in " + VERSION_RESOURCE
                    + " — check Maven resource filtering configuration");
        }
        return version;
    }

    private static String readNativePackageVersion(ClassLoader loader, String classifier) throws IOException {
        String resourcePath = "native/" + classifier + "/" + PLATFORM_PROPERTIES_FILENAME;
        URL resource = loader.getResource(resourcePath);
        if (resource == null) {
            throw new FileNotFoundException("Native runtime metadata not found on classpath: " + resourcePath
                    + " — add the matching classifier JAR to the classpath");
        }

        Properties props = new Properties();
        try (InputStream in = resource.openStream()) {
            props.load(in);
        }
        String version = props.getProperty("version");
        if (version == null || version.isBlank()) {
            throw new IllegalStateException("Blank or missing 'version' property in " + resourcePath);
        }
        return version;
    }

    /**
     * Resolves the runtime binary path using the given parameters. Package-private
     * to allow injection of test doubles in unit tests.
     */

View on GitHub (pinned to cd8cf15dc3)