GoogleContainerTools/jib · error · InvalidGlobalConfigException

'registryMirrors.registry' property is missing

Error message

'registryMirrors.registry' property is missing

What it means

Jib's global config validation rejects a registryMirrors entry whose 'registry' property is null or empty. Each mirrors entry must name the registry it applies to, so an entry without one makes the whole config 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:92

              + configFile);

    } catch (IOException ex) {
      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.
   */

View on GitHub (pinned to fb949e2676)

Solutions

1. Add a non-empty 'registry' value to every entry in the registryMirrors array
2. Check for misspelled property names that leave registry null
3. Remove the incomplete entry if mirrors were not intended for it

Example fix

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

// Validate registryMirrors entries before building
Object mirrors = json.get("registryMirrors");
for (Object o : (java.util.List<?>) mirrors) {
  java.util.Map<?,?> entry = (java.util.Map<?,?>) o;
  Object registry = entry.get("registry");
  if (!(registry instanceof String) || ((String) registry).isEmpty())
    throw new IllegalArgumentException("registryMirrors entry missing 'registry'");
}

When it happens

Trigger: GlobalConfig.from() iterates configJson.getRegistryMirrors() and throws when Strings.isNullOrEmpty(mirrorConfig.getRegistry()) — i.e. a JSON entry like {"mirrors": [...]} with no 'registry' key or "registry": "" in ~/.jib/jib-config.json.

Common situations: Hand-editing the global config and omitting the registry key; copying a partial example from docs; typos like 'registery' silently yielding null registry.

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.mirrors' 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/9808e8158a5b259a. Report an issue: GitHub.