github/copilot-sdk · error · IllegalStateException

Blank or missing 'version' property in — check Maven…

Error message

Blank or missing 'version' property in  — check Maven resource filtering configuration

What it means

The copilot-runtime.properties resource exists but its `version` property is missing or blank. Maven resource filtering should substitute the project version into this property at build time; an unfiltered or misconfigured build leaves it empty, and the loader refuses to use it as a cache key.

Solutions

  1. Verify the properties file template declares version=${project.version} and filtering is enabled for its directory, then rebuild with mvn clean process-resources.
  2. Inspect the built artifact: unzip -p target/classes/copilot-runtime.properties — confirm a concrete version string.
  3. If migrating off Maven, add a build step that writes the actual version into copilot-runtime.properties.
  4. Re-run a full clean build to eliminate stale, unfiltered resource copies.

Example fix

// before: src/main/resources/copilot-runtime.properties (never substituted)
version=

// after
copilot-runtime.properties filter template:
version=${project.version}
// with <filtering>true</filtering> in pom.xml -> builds to version=1.2.0
Defensive patterns

Strategy: validation

Validate before calling

try (InputStream in = getClass().getResourceAsStream("/copilot-runtime.properties")) {
    Properties p = new Properties(); p.load(in);
    if (p.getProperty("version") == null || p.getProperty("version").isBlank())
        throw new IllegalStateException("copilot-runtime.properties has no version — resource filtering misconfigured");
}

Try / catch

try {
    Path runtime = NativeRuntimeLoader.resolve();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Blank or missing 'version' property")) {
        throw new IllegalStateException("Rebuild the SDK: version property was not substituted by Maven filtering", e);
    } else throw e;
}

Prevention

When it happens

Trigger: Building with resource filtering enabled but the properties file not referencing ${project.version}; filtering applied to the wrong resource directory; a placeholder that failed substitution (literal ${project.version} is non-blank, but a miswritten filter leaves it unset); hand-edited properties file.

Common situations: Custom builds (Gradle/Bazel migrations) that copy the template without substituting the version; overridden resource directories in pom.xml dropping the filter config; building from a source checkout with stale filtered output.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

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

     * @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) {
            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");

View on GitHub (pinned to cd8cf15dc3)