GoogleContainerTools/jib · error · IllegalArgumentException

Path starts with forward slash (/): ${relativePath}

Error message

Path starts with forward slash (/): ${relativePath}

What it means

RelativeUnixPath represents a Unix path that must be relative. Its get() factory throws IllegalArgumentException when the string starts with '/', because an absolute path contradicts the type's invariant.

Source

Thrown at jib-build-plan/src/main/java/com/google/cloud/tools/jib/api/buildplan/RelativeUnixPath.java:41

/**
 * Represents a Unix-style path in relative form (does not start at the file system root {@code /}).
 *
 * <p>This class is immutable and thread-safe.
 */
@Immutable
public class RelativeUnixPath {

  /**
   * Gets a new {@link RelativeUnixPath} from a Unix-style path in relative form. The {@code path}
   * must be relative (does not begin with a leading slash {@code /}).
   *
   * @param relativePath the relative path
   * @return a new {@link RelativeUnixPath}
   */
  public static RelativeUnixPath get(String relativePath) {
    if (relativePath.startsWith("/")) {
      throw new IllegalArgumentException("Path starts with forward slash (/): " + relativePath);
    }

    return new RelativeUnixPath(UnixPathParser.parse(relativePath));
  }

  private final List<String> pathComponents;

  /** Instantiate with {@link #get}. */
  private RelativeUnixPath(List<String> pathComponents) {
    this.pathComponents = pathComponents;
  }

  /**
   * Gets the relative Unix path this represents, in a list of components.
   *
   * @return the relative path this represents, in a list of components
   */
  List<String> getRelativePathComponents() {

View on GitHub (pinned to fb949e2676)

Solutions

1. Remove the leading slash and any root component before calling get()
2. Use AbsoluteUnixPath.get() instead if the path is genuinely absolute

Example fix

// before
RelativeUnixPath p = RelativeUnixPath.get("/app/libs");
// after
RelativeUnixPath p = RelativeUnixPath.get("app/libs");

if (path == null || path.startsWith("/")) throw new IllegalArgumentException("path must be relative: " + path);

boolean isRelativeUnixPath(String p) { return p != null && !p.startsWith("/"); }

try { RelativeUnixPath p = RelativeUnixPath.get(path); } catch (IllegalArgumentException e) { p = RelativeUnixPath.get(path.substring(1)); }

When it happens

Trigger: Calling RelativeUnixPath.get("/app/libs") or any string with a leading slash.

Common situations: Mixing up AbsoluteUnixPath and RelativeUnixPath when configuring layer paths or extraction targets; copying an absolute container path into a relative-path field.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Path does not start with forward slash (/): ${unixPath}
• Cannot create AbsoluteUnixPath from non-absolute Path: ${pat
• Cannot resolve against absolute Path: ${relativePath}
• platforms set cannot be empty
• container.appRoot is not an absolute Unix-style path: ${inva

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