GoogleContainerTools/jib · error · IllegalArgumentException

octalPermissions must be a 3-digit octal number (000-777)

Error message

octalPermissions must be a 3-digit octal number (000-777)

What it means

FilePermissions.fromOctalString() parses a 3-digit octal permission string like '644'. It throws IllegalArgumentException when the string does not match the octal pattern (three octal digits 0-7), because it cannot represent valid Unix file permissions otherwise.

Source

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

    map.put(PosixFilePermission.GROUP_READ, 040);
    map.put(PosixFilePermission.GROUP_WRITE, 020);
    map.put(PosixFilePermission.GROUP_EXECUTE, 010);
    map.put(PosixFilePermission.OTHERS_READ, 04);
    map.put(PosixFilePermission.OTHERS_WRITE, 02);
    map.put(PosixFilePermission.OTHERS_EXECUTE, 01);
    PERMISSION_MAP = Collections.unmodifiableMap(map);
  }

  /**
   * Creates a new {@link FilePermissions} from an octal string representation (e.g. "123", "644",
   * "755", etc).
   *
   * @param octalPermissions the octal string representation of the permissions
   * @return a new {@link FilePermissions} with the given permissions
   */
  public static FilePermissions fromOctalString(String octalPermissions) {
    if (!octalPermissions.matches(OCTAL_PATTERN)) {
      throw new IllegalArgumentException(
          "octalPermissions must be a 3-digit octal number (000-777)");
    }
    return new FilePermissions(Integer.parseInt(octalPermissions, 8));
  }

  /**
   * Creates a new {@link FilePermissions} from a set of {@link PosixFilePermission}.
   *
   * @param posixFilePermissions the set of {@link PosixFilePermission}
   * @return a new {@link FilePermissions} with the given permissions
   */
  public static FilePermissions fromPosixFilePermissions(
      Set<PosixFilePermission> posixFilePermissions) {
    int permissionBits = 0;
    for (PosixFilePermission permission : posixFilePermissions) {
      permissionBits |= Objects.requireNonNull(PERMISSION_MAP.get(permission));
    }
    return new FilePermissions(permissionBits);

View on GitHub (pinned to fb949e2676)

Solutions

1. Pass exactly three octal digits 0-7, e.g. "644" or "755"
2. Trim the string and strip a leading '0' or non-digit prefix if present
3. Convert symbolic permissions to octal before calling

Example fix

// before
FilePermissions.fromOctalString("0644");
// after
FilePermissions.fromOctalString("644");

if (perm == null || !perm.trim().matches("[0-7]{3}")) throw new IllegalArgumentException("permissions must be 3 octal digits");

boolean isOctalPermissionString(String s) { return s != null && s.matches("[0-7]{3}"); }

try { FilePermissions p = FilePermissions.fromOctalString(perm); } catch (IllegalArgumentException e) { /* fall back to default 644 */ }

When it happens

Trigger: Calling fromOctalString("7777"), fromOctalString("644 "), fromOctalString("94"), fromOctalString("abc"), or null/empty input.

Common situations: Permissions read from Dockerfiles or config files in formats like '0644' (4 digits), 'rw-r--r--', or containing stray whitespace.

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

• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to
• Invalid hash: ${hash}
• Invalid digest: ${digest}
• ${reference}

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