GoogleContainerTools/jib · error · IllegalStateException

Unknown OS: + rawOsName

Error message

Unknown OS: + rawOsName

What it means

XdgDirectories resolves Jib's cache/config locations per OS using the 'os.name' system property. When the resolved OS name is neither Linux, macOS, nor Windows, it cannot determine a directory and throws this IllegalStateException. The OS is not supported by Jib's XDG directory resolution.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/filesystem/XdgDirectories.java:155

      }
      return localAppData.resolve(windowsSubDirectory);

    } else if (osName.contains("mac") || osName.contains("darwin")) {
      // Use XDG environment variable if set and not empty.
      if (xdgHome != null && !xdgHome.trim().isEmpty()) {
        return Paths.get(xdgHome).resolve(JIB_SUBDIRECTORY_OTHER);
      }

      // Use '~/Library/...' for macOS.
      Path macDirectory = Paths.get(userHome, "Library", macFolder);
      if (!Files.exists(macDirectory)) {
        LOGGER.warning(() -> macDirectory + " does not exist");
        return xdgPath.resolve(JIB_SUBDIRECTORY_OTHER);
      }
      return macDirectory.resolve(JIB_SUBDIRECTORY_OTHER);
    }

    throw new IllegalStateException("Unknown OS: " + rawOsName);
  }

  private XdgDirectories() {}
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Use a supported OS (Linux, macOS, Windows) or a standard JVM whose os.name is conventional
2. Run on a standard Linux base image in containers/CI
3. Remove any custom -Dos.name JVM flag
4. As a workaround, pre-create the expected directory or file an issue upstream to support the OS

Example fix

// before (Dockerfile)
FROM some-unusual-os
CMD java ... -Dos.name=WeirdOS
// after
FROM eclipse-temurin:17
CMD java -jar jib-build.jar # standard os.name=Linux

String os = System.getProperty("os.name", "").toLowerCase();
boolean supported = os.contains("linux") || os.contains("mac") || os.contains("windows");
if (!supported) throw new IllegalStateException("Jib XDG directories unsupported on OS: " + os);

boolean isJibSupportedOs() { String os = System.getProperty("os.name", "").toLowerCase(); return os.contains("linux") || os.contains("mac") || os.contains("windows"); }

try { jibStep(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unknown OS")) { failBuild("Run Jib on Linux/macOS/Windows"); } throw e; }

When it happens

Trigger: Running Jib on a JVM whose os.name is not recognized (e.g. unusual Linux distro reporting a nonstandard name, Solaris, AIX, FreeBSD, or a JVM with a modified os.name property).

Common situations: Building inside unusual containers or CI images with patched JVMs, running on BSD/Solaris, or setting -Dos.name=... to nonstandard values.

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

• platform does not support TLS protocol
• SHA-256 algorithm implementation not found - might be a brok
• Failed to construct entrypoint on JavaContainerBuilder; jvmF
• Failed to construct entrypoint because no files were added t
• <field> is required but not set

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/d735de01fd7aa4b9. Report an issue: GitHub.