GoogleContainerTools/jib · error · InvalidGlobalConfigException

'registryMirrors.mirrors' property is missing

Error message

'registryMirrors.mirrors' property is missing

What it means

Jib's global config validation rejects a registryMirrors entry whose 'mirrors' list is empty. Every registry entry must include at least one mirror URL; otherwise the config is invalid and the build fails with InvalidGlobalConfigException.

Source

Thrown at jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/globalconfig/GlobalConfig.java:95

      throw new IOException(
          "Failed to create, open, or parse global Jib config file; see "
              + "https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#where-is-the-global-jib-configuration-file-and-how-i-can-configure-it "
              + "to fix or you may need to delete "
              + configFile,
          ex);
    }
  }

  private static GlobalConfig from(GlobalConfigTemplate configJson)
      throws InvalidGlobalConfigException {
    ImmutableListMultimap.Builder<String, String> registryMirrors = ImmutableListMultimap.builder();
    for (RegistryMirrorsTemplate mirrorConfig : configJson.getRegistryMirrors()) {
      // validation
      if (Strings.isNullOrEmpty(mirrorConfig.getRegistry())) {
        throw new InvalidGlobalConfigException("'registryMirrors.registry' property is missing");
      }
      if (mirrorConfig.getMirrors().isEmpty()) {
        throw new InvalidGlobalConfigException("'registryMirrors.mirrors' property is missing");
      }

      registryMirrors.putAll(mirrorConfig.getRegistry(), mirrorConfig.getMirrors());
    }

    return new GlobalConfig(configJson.isDisableUpdateCheck(), registryMirrors.build());
  }

  /**
   * Returns the config directory set by {@link PropertyNames#CONFIG_DIRECTORY} if not null,
   * otherwise returns the default config directory.
   *
   * @return the config directory set by {@link PropertyNames#CONFIG_DIRECTORY} if not null,
   *     otherwise returns the default config directory.
   */
  public static Path getConfigDir() {
    String configDirProperty = System.getProperty(PropertyNames.CONFIG_DIRECTORY);
    if (!Strings.isNullOrEmpty(configDirProperty)) {

View on GitHub (pinned to fb949e2676)

Solutions

1. Provide at least one mirror URL in each registryMirrors entry's 'mirrors' array
2. Remove the entry entirely if no mirrors are needed for that registry
3. Verify the property is named 'mirrors' (plural) and is an array of strings

Example fix

// before: ~/.jib/jib-config.json
{ "registryMirrors": [ { "registry": "docker.io", "mirrors": [] } ] }
// after
{ "registryMirrors": [ { "registry": "docker.io", "mirrors": ["mirror.gcr.io"] } ] }

// Ensure each mirrors array is non-empty
for (Object o : (java.util.List<?>) json.get("registryMirrors")) {
  java.util.List<?> m = (java.util.List<?>) ((java.util.Map<?,?>) o).get("mirrors");
  if (m == null || m.isEmpty())
    throw new IllegalArgumentException("registryMirrors entry missing non-empty 'mirrors'");
}

When it happens

Trigger: GlobalConfig.from() throws when mirrorConfig.getMirrors().isEmpty() — a JSON entry like {"registry": "docker.io", "mirrors": []} or a missing 'mirrors' key in ~/.jib/jib-config.json.

Common situations: Adding a registry entry as a placeholder before filling in mirrors; hand-editing the config and leaving the array empty; JSON tooling writing null for an unset list.

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

• 'registryMirrors.registry' property is missing
• octalPermissions must be a 3-digit octal number (000-777)
• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to
• Invalid hash: ${hash}

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