apache/hadoop · error · IllegalArgumentException

GID must fit in 24 bits

Error message

GID must fit in 24 bits

What it means

Error "GID must fit in 24 bits" thrown in apache/hadoop.

Source

Thrown at hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/UGIResolver.java:64

   * Endian).
   * The first and the second parts are the string ids of the user and
   * group name, and the last 16 bits are the permission bits.
   * @param owner name of owner
   * @param group name of group
   * @param permission Permission octects
   * @return FSImage encoding of permissions
   */
  protected final long buildPermissionStatus(
      String owner, String group, short permission) {

    long userId = users.get(owner);
    if (0L != ((~USER_GROUP_STRID_MASK) & userId)) {
      throw new IllegalArgumentException("UID must fit in 24 bits");
    }

    long groupId = groups.get(group);
    if (0L != ((~USER_GROUP_STRID_MASK) & groupId)) {
      throw new IllegalArgumentException("GID must fit in 24 bits");
    }
    return ((userId & USER_GROUP_STRID_MASK) << USER_STRID_OFFSET)
        | ((groupId & USER_GROUP_STRID_MASK) << GROUP_STRID_OFFSET)
        | permission;
  }

  private final Map<String, Integer> users;
  private final Map<String, Integer> groups;

  public UGIResolver() {
    this(new HashMap<String, Integer>(), new HashMap<String, Integer>());
  }

  UGIResolver(Map<String, Integer> users, Map<String, Integer> groups) {
    this.users = users;
    this.groups = groups;
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Remap groups so every GID is below 2^24 before generating the image.

When it happens

Trigger: A group mapping supplied to UGIResolver produces a GID larger than 24 bits, which cannot be encoded into the fsimage's user/group ID space.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/b9c2a369c4093bf1. Report an issue: GitHub.