elastic/elasticsearch · error · IllegalArgumentException

permissions [{}] out of range

Error message

permissions [{}] out of range

What it means

Thrown by PermissionUtils.permissions(int) when a single POSIX permission octet is outside 0..7. The method builds the rwx string for one 3-bit group. permissionsFromInt masks each group with & 07, so through that path the value is provably 0..7 and this guard is effectively unreachable; it is a defensive assertion against direct or future misuse.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/util/PermissionUtils.java:38

public class PermissionUtils {

    public static void chmod(Path path, int mode) throws IOException {
        final PosixFileAttributeView view = Files.getFileAttributeView(path, PosixFileAttributeView.class);
        if (view != null && (mode != 0)) {
            final Set<PosixFilePermission> permissions = permissionsFromInt(mode);
            Files.setPosixFilePermissions(path, permissions);
        }
    }

    private static Set<PosixFilePermission> permissionsFromInt(int mode) {
        return PosixFilePermissions.fromString(
            permissions((mode >> 6) & 07) + permissions((mode >> 3) & 07) + permissions((mode >> 0) & 07)
        );
    }

    private static String permissions(final int permissions) {
        if (permissions < 0 || permissions > 7) {
            throw new IllegalArgumentException("permissions [" + permissions + "] out of range");
        }
        final StringBuilder sb = new StringBuilder(3);
        if ((permissions & 4) == 4) {
            sb.append('r');
        } else {
            sb.append('-');
        }
        if ((permissions & 2) == 2) {
            sb.append('w');
        } else {
            sb.append('-');
        }
        if ((permissions & 1) == 1) {
            sb.append('x');
        } else {
            sb.append('-');
        }
        return sb.toString();

View on GitHub (pinned to db6a809a66)

Solutions

1. Mask the input with & 07 before passing it in.
2. Validate the source mode is a valid POSIX octal (e.g. 0644, 0755) before conversion.
3. Keep the permissionsFromInt indirection so the mask is always applied.

Example fix

// before
permissions(rawMode);
// after
permissions(rawMode & 07);

if (perm < 0 || perm > 7) {
    throw new IllegalArgumentException("permissions [" + perm + "] out of range");
}
// safe to convert

When it happens

Trigger: A direct call to the private permissions(int) with a value < 0 or > 7, or a future refactor that feeds an unmasked integer. Via permissionsFromInt(mode) the mask guarantees 0..7 and the exception cannot fire.

Common situations: Effectively only reachable through reflection or an incorrect refactor that bypasses the & 07 mask; not a normal user-facing error.

Related errors

• Failed to create parent directory '%s' when creating directo
• Failed to create directory '%s'
• platform cannot be set on elasticsearch distribution [${name
• bundledJdk cannot be set on elasticsearch distribution [${na
• ${className} does not support remove()

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/1f82157e91cf3cc3. Report an issue: GitHub.