GoogleContainerTools/jib · error · UnknownManifestFormatException

Unknown schemaVersion: + schemaVersion + " - only 1 and 2 ar

Error message

Unknown schemaVersion: + schemaVersion + " - only 1 and 2 are supported"

What it means

Thrown by AbstractManifestPuller.getManifestTemplateFromJson when the manifest's schemaVersion is neither 1 nor 2 (or absent mediaType handling for 2 already failed). Jib supports only Docker schema versions 1 and 2, so any other integer is rejected. It surfaces as UnknownManifestFormatException listing the unsupported version.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/registry/AbstractManifestPuller.java:187

      if (OciManifestTemplate.MANIFEST_MEDIA_TYPE.equals(mediaType)) {
        return manifestTemplateClass.cast(
            JsonTemplateMapper.readJson(jsonString, OciManifestTemplate.class));
      }
      if (V22ManifestTemplate.MANIFEST_MEDIA_TYPE.equals(mediaType)) {
        return manifestTemplateClass.cast(
            JsonTemplateMapper.readJson(jsonString, V22ManifestTemplate.class));
      }
      if (V22ManifestListTemplate.MANIFEST_MEDIA_TYPE.equals(mediaType)) {
        return manifestTemplateClass.cast(
            JsonTemplateMapper.readJson(jsonString, V22ManifestListTemplate.class));
      }
      if (OciIndexTemplate.MEDIA_TYPE.equals(mediaType)) {
        return manifestTemplateClass.cast(
            JsonTemplateMapper.readJson(jsonString, OciIndexTemplate.class));
      }
      throw new UnknownManifestFormatException("Unknown mediaType: " + mediaType);
    }
    throw new UnknownManifestFormatException(
        "Unknown schemaVersion: " + schemaVersion + " - only 1 and 2 are supported");
  }

  @Override
  public R handleHttpResponseException(ResponseException responseException)
      throws ResponseException, RegistryErrorException {
    throw responseException;
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

Check the manifest's schemaVersion value returned by the registry with a raw curl request.
Point Jib at a registry implementing the Docker Registry API v2 (schemaVersion 1 or 2).
Upgrade Jib in case a newer version supports the schema version in question.
Remove/fix any proxy or middleware that rewrites manifest JSON.

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: schemaVersion must be 1 or 2
// curl -s <manifest-url> | jq '.schemaVersion'
// expect: 1 or 2

Try / catch

// catch and diagnose unsupported schema versions
try {
    jibContainerBuilder.containerize();
} catch (RegistryErrorException e) {
    if (e.getMessage().contains("Unknown schemaVersion")) {
        throw new IllegalStateException("Registry serves an unsupported manifest schema version — use a Docker Registry v2-compatible registry", e);
    }
    throw e;
}

Prevention

Use registries implementing the Docker Registry HTTP API v2.
Strip middleware that injects custom schema versions into responses.
Keep Jib updated for future schema support.

When it happens

Trigger: A registry returns a manifest with schemaVersion 3 or 0, or an unusual integer — e.g. a hypothetical future registry format or a corrupted response.

Common situations: Forward-looking/nonstandard registries, proxies injecting their own schema versions, or response corruption from middleware.

Related errors

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