GoogleContainerTools/jib · error · IOException

Failed to create, open, or parse global Jib config file…

Error message

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}

What it means

Jib throws an IOException with this message when it cannot create, open, or parse the global Jib configuration file (~/.jib/jib-config.json), wrapping the original exception. The appended FAQ link explains where the file lives and that deleting it usually resolves the problem.

Solutions

  1. Delete the global config file shown in the message so Jib regenerates defaults
  2. Check permissions on ~/.jib and the config file (must be readable/writable by the build user)
  3. If ~/.jib is a directory-where-file or file-where-directory, fix its type
  4. Repair the JSON content per the linked FAQ

Example fix

// before (shell)
ls -l ~/.jib/jib-config.json   # unreadable, owned by root
// after
sudo chown $(whoami) ~/.jib/jib-config.json
# or simply remove it to regenerate:
rm ~/.jib/jib-config.json
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check readability before invoking Jib
java.nio.file.Path cfg = java.nio.file.Path.of(System.getProperty("user.home"), ".jib", "jib-config.json");
if (java.nio.file.Files.exists(cfg) && !java.nio.file.Files.isReadable(cfg)) {
  throw new IllegalStateException("Global Jib config not readable: " + cfg);
}

Try / catch

try {
  GlobalConfig.readConfig(configDir);
} catch (IOException e) {
  logger.warn("Deleting unreadable/corrupt global Jib config: {}", e.getMessage());
  Files.deleteIfExists(configDir.resolve("jib-config.json"));
  GlobalConfig.readConfig(configDir);
}

Prevention

When it happens

Trigger: The catch (IOException ex) branch of GlobalConfig.readConfig: filesystem errors creating/reading the file (bad permissions, disk issues), or parsing errors from reading the JSON template.

Common situations: Read-only or permission-restricted home directory; ~/.jib exists as a file instead of a directory; corrupted config file that fails JSON parsing; disk full or NFS/permission issues in CI containers.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

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

View on GitHub (pinned to fb949e2676)