elastic/elasticsearch · error · PolicyValidationException

invalid mode: {}, valid values: [read, read_write]

Error message

invalid mode: {}, valid values: [read, read_write]

What it means

Thrown by FilesEntitlement.parseMode when the `mode` string on a files-entitlement entry is neither "read" nor "read_write". Mode selects read-only vs read-write access for the listed path and is mandatory, so an unknown value cannot be silently defaulted.

Source

Thrown at libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java:164

        @Override
        public Stream<Path> resolvePaths(PathLookup pathLookup) {
            return pathLookup.resolveSettingPaths(baseDir, setting);
        }

        @Override
        public String description() {
            return Strings.format("[%s] <%s>%s<%s>%s", mode, baseDir, SEPARATOR, setting, exclusive ? " (exclusive)" : "");
        }
    }

    private static Mode parseMode(String mode) {
        if (mode.equals("read")) {
            return Mode.READ;
        } else if (mode.equals("read_write")) {
            return Mode.READ_WRITE;
        } else {
            throw new PolicyValidationException("invalid mode: " + mode + ", valid values: [read, read_write]");
        }
    }

    private static Platform parsePlatform(String platform) {
        if (platform.equals("linux")) {
            return Platform.LINUX;
        } else if (platform.equals("macos")) {
            return Platform.MACOS;
        } else if (platform.equals("windows")) {
            return Platform.WINDOWS;
        } else {
            throw new PolicyValidationException("invalid platform: " + platform + ", valid values: [linux, macos, windows]");
        }
    }

    private static BaseDir parseBaseDir(String baseDir) {
        return switch (baseDir) {
            case "config" -> BaseDir.CONFIG;

View on GitHub (pinned to db6a809a66)

Solutions

1. Set `mode` to exactly "read" for read-only access.
2. Set `mode` to exactly "read_write" for read+write access (underscore, lowercase).
3. Re-encode/redeploy the policy patch and restart.

Example fix

// before
{ "path": "/var/log/es", "mode": "read-write" }

// after
{ "path": "/var/log/es", "mode": "read_write" }

private static final Set<String> ALLOWED_MODES = Set.of("read", "read_write");

public static void validateMode(String mode) {
    if (!ALLOWED_MODES.contains(mode)) {
        throw new IllegalArgumentException("mode must be one of " + ALLOWED_MODES + ", got: " + mode);
    }
}

public static boolean isValidMode(String mode) {
    return "read".equals(mode) || "read_write".equals(mode);
}

When it happens

Trigger: A policy file lists a files entitlement entry whose `mode` field is something other than the two allowed literals (for example "write", "rw", "READ", "read-only", or a typo like "read-write" with a hyphen).

Common situations: Author guesses the mode literal instead of consulting the docs; migrating from a different permission vocabulary (e.g. "rw"); using uppercase or hyphenated variants; copy-pasting from a sample that used a different schema.

Related errors

• invalid platform: {}, valid values: [linux, macos, windows]
• invalid relative directory: {}, valid values: [config, data,
• must specify at least one path
• expected [{}] to be type [String] but found type [{}]
• expected [{}] to be type [boolean] but found type [{}]

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