GoogleContainerTools/jib · error · InvalidGlobalConfigException

${message}; see https://github.com/GoogleContainerTools/jib/

Error message

${message}; 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}

What it means

Jib wraps the message of an InvalidGlobalConfigException thrown while parsing the global Jib configuration file (~/.jib/jib-config.json), appending a link to the FAQ explaining where the file lives and how to fix it. It indicates the config file exists but its contents violate Jib's schema (e.g. a property has the wrong type or an invalid value). The message suggests fixing the file or deleting it to restore defaults.

Source

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

      // Generate config file if it doesn't exist
      Files.createDirectories(configDir);
      Path tempConfigFile = Files.createTempFile(configDir, CONFIG_FILENAME, null);
      tempConfigFile.toFile().deleteOnExit();

      GlobalConfigTemplate configJson = new GlobalConfigTemplate();
      try (OutputStream outputStream = Files.newOutputStream(tempConfigFile)) {
        JsonTemplateMapper.writeTo(configJson, outputStream);
        Files.move(tempConfigFile, configFile);
        return from(configJson);

      } catch (FileAlreadyExistsException ex) {
        // Perhaps created concurrently. Read again.
        return readConfig(configDir);
      }

    } catch (InvalidGlobalConfigException ex) {
      throw new InvalidGlobalConfigException(
          ex.getMessage()
              + "; 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);

    } 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();

View on GitHub (pinned to fb949e2676)

Solutions

1. Open the config file path shown in the message and fix the invalid property per the linked FAQ
2. Validate each registryMirrors entry has non-empty 'registry' and non-empty 'mirrors' array
3. Delete the config file to fall back to defaults and re-create it carefully
4. If it was created concurrently by another build, simply re-run; readConfig retries once on FileAlreadyExistsException but an invalid concurrent write still surfaces this

Example fix

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

// Validate global jib config before building
import com.google.cloud.tools.jib.plugins.common.globalconfig.GlobalConfig;
java.nio.file.Path dir = java.nio.file.Path.of(System.getProperty("user.home"), ".jib");
if (java.nio.file.Files.exists(dir.resolve("jib-config.json"))) {
  try { GlobalConfig.readConfig(dir); } catch (Exception e) { throw new IllegalStateException("Fix or delete " + dir.resolve("jib-config.json"), e); }
}

When it happens

Trigger: Thrown by GlobalConfig.readConfig when reading the global config file raises InvalidGlobalConfigException from the internal from() validation; the original message is preserved and the FAQ URL plus the config file path are appended. Any schema violation detected in from() (empty registry, empty mirrors list) or JSON binding failure mapped to InvalidGlobalConfigException triggers this.

Common situations: Users hand-edit ~/.jib/jib-config.json to add registry mirrors and get a property name or type wrong; files written by an older Jib version with a schema no longer accepted; malformed JSON partially parsed then rejected by validation.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to create, open, or parse global Jib config file; see
• 'registryMirrors.registry' property is missing
• 'registryMirrors.mirrors' property is missing
• 'mainClass' configured in ${jarPluginName} is not a valid Ja
• mainClass, extraClasspath, jvmFlags, and expandClasspathDepe

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