What causes "Invalid volume path: + volume" in GoogleContainerTools/jib?

Prefix the volume path with '/' so it is an absolute container path (e.g. '/data').

GoogleContainerTools/jib · error · BadContainerConfigurationFormatException

Invalid volume path: + volume

Error message

Invalid volume path: + volume

What it means

Thrown by JsonToImageTranslator.volumeMapToSet when a key in the container configuration's 'volumes' map cannot be parsed as an absolute UNIX path (AbsoluteUnixPath.get throws IllegalArgumentException). Jib requires volume entries to be absolute container paths like '/data'. It surfaces as BadContainerConfigurationFormatException naming the bad path.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/image/json/JsonToImageTranslator.java:271

   * {"/var/log/my-app-logs":{}}} -> {@code AbsoluteUnixPath().get("/var/log/my-app-logs")}).
   *
   * @param volumeMap the map to convert
   * @return a set of {@link AbsoluteUnixPath}s
   */
  @VisibleForTesting
  static ImmutableSet<AbsoluteUnixPath> volumeMapToSet(
      @Nullable Map<String, Map<String, String>> volumeMap)
      throws BadContainerConfigurationFormatException {
    if (volumeMap == null) {
      return ImmutableSet.of();
    }

    ImmutableSet.Builder<AbsoluteUnixPath> volumeList = ImmutableSet.builder();
    for (String volume : volumeMap.keySet()) {
      try {
        volumeList.add(AbsoluteUnixPath.get(volume));
      } catch (IllegalArgumentException exception) {
        throw new BadContainerConfigurationFormatException("Invalid volume path: " + volume);
      }
    }

    return volumeList.build();
  }

  private JsonToImageTranslator() {}
}

View on GitHub (pinned to fb949e2676)

Solutions

Prefix the volume path with '/' so it is an absolute container path (e.g. '/data').
Remove any host-side or Windows-style path components; only container-internal absolute paths are allowed.
Check for empty strings or trailing whitespace in the volumes keys.

Example fix

// before
volumes: "data"
// after
volumes: "/data"

Defensive patterns

Strategy: validation

Validate before calling

// validate volume paths before configuring Jib
for (String volume : volumesConfig.keySet()) {
    if (!volume.startsWith("/"))
        throw new IllegalArgumentException("Invalid volume path: " + volume);
}

Prevention

Always use absolute, POSIX-style container paths ('/data'), never host or relative paths.
Trim whitespace and reject empty strings in volume config before building.
Reuse Jib's AbsoluteUnixPath.get() in your own validation to mirror its rules.

When it happens

Trigger: A volumes entry that is relative ('data'), empty (''), contains invalid characters, or is a Windows-style path ('C:\\data') passed via containerConfiguration.volumes.

Common situations: Users mirroring Docker Compose volume syntax with host paths, typos dropping the leading slash, or config generated programmatically with relative path variables.

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/3992d1d43602fd72. Report an issue: GitHub.