GoogleContainerTools/jib · error · InvalidContainerVolumeException

${path}

Error message

${path}

What it means

Jib's getVolumesSet converts each configured container volume path to an AbsoluteUnixPath. If a configured volume string is not a valid absolute Unix path (e.g. relative, backslashes, or empty), the IllegalArgumentException from AbsoluteUnixPath.get is rethrown as InvalidContainerVolumeException with the offending path as both value and message template.

Source

Thrown at jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/PluginConfigurationProcessor.java:838

  }

  /**
   * Parses the list of raw volumes directories to a set of {@link AbsoluteUnixPath}.
   *
   * @param rawConfiguration raw configuration data
   * @return the set of parsed volumes.
   * @throws InvalidContainerVolumeException if {@code volumes} are not valid absolute Unix paths
   */
  @VisibleForTesting
  static Set<AbsoluteUnixPath> getVolumesSet(RawConfiguration rawConfiguration)
      throws InvalidContainerVolumeException {
    Set<AbsoluteUnixPath> volumes = new HashSet<>();
    for (String path : rawConfiguration.getVolumes()) {
      try {
        AbsoluteUnixPath absoluteUnixPath = AbsoluteUnixPath.get(path);
        volumes.add(absoluteUnixPath);
      } catch (IllegalArgumentException exception) {
        throw new InvalidContainerVolumeException(path, path, exception);
      }
    }

    return volumes;
  }

  /**
   * Gets the value of the {@code appRoot} parameter. If the parameter is empty, returns {@code
   * /var/lib/jetty/webapps/ROOT} for WAR projects or {@link JavaContainerBuilder#DEFAULT_APP_ROOT}
   * for other projects.
   *
   * @param rawConfiguration raw configuration data
   * @param projectProperties the project properties
   * @return the app root value
   * @throws InvalidAppRootException if {@code appRoot} value is not an absolute Unix path
   */
  @VisibleForTesting
  static AbsoluteUnixPath getAppRootChecked(

View on GitHub (pinned to fb949e2676)

Solutions

  1. Change the volume to an absolute Unix path starting with '/', e.g. /app/data.
  2. Replace backslashes with forward slashes and drop drive letters if migrating from Windows path conventions.
  3. Remove empty or whitespace-only entries from the volumes list.

Example fix

// before (Gradle)
container.volumes = ['app/data']
// after
container.volumes = ['/app/data']
Defensive patterns

Strategy: validation

Validate before calling

// Validate volume paths before configuring Jib
volumes.forEach(v -> {
  if (!v.startsWith("/"))
    throw new IllegalArgumentException("volume must be absolute unix path: " + v);
});

Try / catch

try {
  processCommonConfiguration(...);
} catch (InvalidContainerVolumeException e) {
  logger.error("Invalid volume '" + e.getInvalidVolume() + "'; use absolute unix paths like /app/data");
}

Prevention

When it happens

Trigger: processCommonConfiguration -> getVolumesSet encounters a <volumes>/<volume> value where AbsoluteUnixPath.get(path) throws IllegalArgumentException — path does not start with '/' or contains invalid segments.

Common situations: Writing volumes: [app/data] without leading slash; copying Windows-style paths like C:\data; typos such as a leading space; empty string in the volumes list.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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