github/copilot-sdk · error · IllegalStateException

Missing version resource: — ensure Maven resource…

Error message

Missing version resource:  — ensure Maven resource filtering has run (mvn process-resources)

What it means

readVersion() could not find the copilot-runtime.properties resource on the classpath. This file is produced by Maven resource filtering at build time and carries the SDK version used as the cache key, so its absence means the SDK was built or packaged incorrectly.

Solutions

Run a clean full build: mvn clean process-resources (or mvn clean install).
Enable Maven resource filtering on the directory containing copilot-runtime.properties in pom.xml (<filtering>true</filtering>).
Check packaging/shade config isn't excluding copilot-runtime.properties from the final JAR.
If using a non-Maven build, generate copilot-runtime.properties with a `version` property equivalent to the filtered output.

Example fix

// before (pom.xml): filtering disabled
<resource>
  <directory>src/main/resources</directory>
</resource>

// after
<resource>
  <directory>src/main/resources</directory>
  <filtering>true</filtering>
</resource>

Defensive patterns

Strategy: validation

Validate before calling

boolean versionResourcePresent = NativeRuntimeLoader.class.getClassLoader()
    .getResource("copilot-runtime.properties") != null;
if (!versionResourcePresent) throw new IllegalStateException("Run 'mvn clean process-resources' — copilot-runtime.properties missing");

Try / catch

try {
    Path runtime = NativeRuntimeLoader.resolve();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Missing version resource")) {
        throw new IllegalStateException("Build artifact is broken: rebuild with Maven resource filtering (mvn clean install)", e);
    } else throw e;
}

Prevention

Always build the SDK with a full mvn clean install so filtering runs.
Enable <filtering>true</filtering> for the resource directory containing copilot-runtime.properties.
Verify built JARs contain a concrete version in copilot-runtime.properties before publishing.
In IDEs, run the Maven process-resources phase or import via the Maven lifecycle, not raw javac.

When it happens

Trigger: Running code from a build where `mvn process-resources` never ran or filtering was disabled; copying classes into a JAR manually; the resource was excluded by packaging config; running from an IDE with an unfiltered target/classes.

Common situations: First `mvn compile` in a fresh clone without resource filtering enabled for copilot-runtime.properties; custom build (Gradle, Bazel) that doesn't replicate Maven filtering; shaded JAR excluding *.properties; corrupted incremental build.

Related errors

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

Appendix: source

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

        }
        throw new IOException("Copilot CLI executable not found at " + cliPath
                + " — the classifier JAR must contain both runtime.node and the copilot binary");
    }

    /**
     * Reads the SDK version from the filtered {@code copilot-runtime.properties}
     * resource.
     *
     * @return the version string
     * @throws IOException
     *             if the resource cannot be read
     * @throws IllegalStateException
     *             if the resource is missing or the version property is blank
     */
    static String readVersion(ClassLoader loader) throws IOException {
        URL resource = loader.getResource(VERSION_RESOURCE);
        if (resource == null) {
            throw new IllegalStateException("Missing version resource: " + VERSION_RESOURCE
                    + " — 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) {

View on GitHub (pinned to cd8cf15dc3)