github/copilot-sdk · error · IllegalStateException

Unsupported os.name: + osName

Error message

Unsupported os.name: + osName

What it means

PlatformDetector.detectOs maps the JVM's os.name system property to a platform classifier ('win32', 'linux', or macOS). If the normalized os.name contains none of the recognized substrings (mac/win/linux), it throws IllegalStateException. The library only ships native runtimes for these platforms, so an unknown OS cannot be served.

Solutions

  1. Run the library on a supported OS (macOS, Windows, Linux) or a JVM reporting a standard os.name.
  2. Override the os.name system property (-Dos.name=Linux) when running on a compatible platform with a nonstandard report — e.g. FreeBSD Linux emulation.
  3. Check for code/tests that set os.name to a fake value before the loader initializes.
  4. File/await upstream support for the unsupported OS classifier.

Example fix

// before (FreeBSD, os.name=FreeBSD)
java -jar app.jar
// after (Linux emulation layer)
java -Dos.name=Linux -jar app.jar
Defensive patterns

Strategy: validation

Validate before calling

// Java: check OS support before initializing the loader
String osName = System.getProperty("os.name", "").toLowerCase(Locale.ROOT);
boolean supported = osName.contains("mac") || osName.contains("darwin") || osName.contains("win") || osName.contains("linux");
if (!supported) throw new IllegalStateException("Unsupported os.name: " + osName + "; run on macOS/Windows/Linux");

Try / catch

try { loader.loadRuntime(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unsupported os.name")) { // fail fast with a supported-platforms message, or retry with -Dos.name override } else throw e; }

Prevention

When it happens

Trigger: Any load path that triggers platform detection on a JVM whose os.name is exotic — e.g. Solaris, AIX, FreeBSD, or a JVM reporting a custom/blank os.name. Note the message text itself literally contains '+ osName' due to a formatting typo in the source.

Common situations: Running on FreeBSD/OpenBSD with the Linux compatibility layer not fully reporting 'linux'; exotic/embedded JVMs (e.g. some J2ME-like or custom builds) with unusual os.name values; cross-compilation/test environments setting os.name deliberately.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/PlatformDetector.java:116

     *
     * @return platform classifier string
     */
    public static String detectClassifier() {
        return detectClassifier(detectOs(), detectArch(), detectLinuxLibc());
    }

    static String detectOs(String osName) {
        String normalized = osName.toLowerCase(Locale.ROOT);
        if (normalized.contains("mac") || normalized.contains("darwin")) {
            return "darwin";
        }
        if (normalized.contains("win")) {
            return "win32";
        }
        if (normalized.contains("linux")) {
            return "linux";
        }
        throw new IllegalStateException("Unsupported os.name: " + osName);
    }

    static String detectArch(String osArch) {
        String normalized = osArch.toLowerCase(Locale.ROOT).replace('-', '_');
        if (normalized.equals("amd64") || normalized.equals("x86_64") || normalized.equals("x64")) {
            return "x64";
        }
        if (normalized.equals("aarch64") || normalized.equals("arm64")) {
            return "arm64";
        }
        throw new IllegalStateException("Unsupported os.arch: " + osArch);
    }

    static LinuxLibc detectLinuxLibc(Path executablePath) {
        try {
            return detectLinuxLibc(readPrefix(executablePath, ELF_HEADER_PROBE_BYTES));
        } catch (IOException ex) {
            return LinuxLibc.UNKNOWN;

View on GitHub (pinned to cd8cf15dc3)