GoogleContainerTools/jib · error · InvalidPlatformException

platform configuration is missing an OS value

Error message

platform configuration is missing an OS value

What it means

Jib validates each entry in the <platforms>/<platform> configuration and requires both an architecture and an OS. When a platform block omits <os>, Jib throws InvalidPlatformException with 'platform configuration is missing an OS value' and echoes the partially-specified platform (e.g. architecture=amd64, os=<missing>). This happens while processing common plugin configuration before any image build begins.

Source

Thrown at jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/PluginConfigurationProcessor.java:813

   * @throws InvalidPlatformException if there exists a {@link PlatformConfiguration} in the
   *     specified platforms list that is missing required fields or has invalid values
   */
  @VisibleForTesting
  static Set<Platform> getPlatformsSet(RawConfiguration rawConfiguration)
      throws InvalidPlatformException {
    Set<Platform> platforms = new LinkedHashSet<>();
    for (PlatformConfiguration platformConfiguration : rawConfiguration.getPlatforms()) {
      Optional<String> architecture = platformConfiguration.getArchitectureName();
      Optional<String> os = platformConfiguration.getOsName();
      String platformToString =
          "architecture=" + architecture.orElse("<missing>") + ", os=" + os.orElse("<missing>");

      if (!architecture.isPresent()) {
        throw new InvalidPlatformException(
            "platform configuration is missing an architecture value", platformToString);
      }
      if (!os.isPresent()) {
        throw new InvalidPlatformException(
            "platform configuration is missing an OS value", platformToString);
      }

      platforms.add(new Platform(architecture.get(), os.get()));
    }
    return platforms;
  }

  /**
   * Parses the list of raw volumes directories to a set of {@link AbsoluteUnixPath}.
   *
   * @param rawConfiguration raw configuration data
   * @return the set of parsed volumes.
   * @throws InvalidContainerVolumeException if {@code volumes} are not valid absolute Unix paths
   */
  @VisibleForTesting
  static Set<AbsoluteUnixPath> getVolumesSet(RawConfiguration rawConfiguration)
      throws InvalidContainerVolumeException {

View on GitHub (pinned to fb949e2676)

Solutions

1. Add the <os> element (usually linux) to the platform block: <platform><architecture>amd64</architecture><os>linux</os></platform>.
2. If configuring programmatically, call setOsName(...) (or the builder equivalent) on every PlatformConfiguration before passing it to Jib.
3. Check the '<missing>' value in the exception message to confirm which platform block is incomplete, then fix that specific entry.

Example fix

// before (Maven)
<platform><architecture>amd64</architecture></platform>
// after
<platform><architecture>amd64</architecture><os>linux</os></platform>

// Before running Jib, check each configured platform
platforms.forEach(p -> {
  if (p.getArchitecture() == null || p.getArchitecture().isEmpty())
    throw new IllegalStateException("platform missing architecture");
  if (p.getOs() == null || p.getOs().isEmpty())
    throw new IllegalStateException("platform missing os");
});

// Maven/Gradle fail before the build; if calling Jib APIs directly:
try {
  Set<Platform> platforms = getPlatformsSet(rawConfig);
} catch (InvalidPlatformException e) {
  logger.error("Fix the platform config: " + e.getMessage());
}

When it happens

Trigger: Calling processCommonConfiguration -> getPlatformsSet when a platform configuration entry (Maven <platform> or Gradle platform{...} block, or a JibSystemProperties/extension-supplied PlatformConfiguration) has an architecture but getOsName() returns empty Optional.

Common situations: Users write only <architecture>amd64</architecture> in the platform block assuming OS defaults to linux; platform blocks built programmatically (e.g. from YAML or build scripts) that set architecture but forget os; empty <os></os> tags parsed as missing.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• ${path}
• ${appRoot}
• packaged containerizing mode for WAR is not yet supported
• ${modificationTime}
• ${configuredCreationTime}

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