elastic/elasticsearch · error · PolicyValidationException

invalid platform: {}, valid values: [linux, macos, windows]

Error message

invalid platform: {}, valid values: [linux, macos, windows]

What it means

Thrown by FilesEntitlement.parsePlatform when the `platform` field on a files-entitlement entry is anything other than "linux", "macos", or "windows". Platform optionally restricts an entry to a single OS; an unknown value cannot be matched at runtime.

Source

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

    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;
            case "data" -> BaseDir.DATA;
            case "home" -> BaseDir.USER_HOME;
            case "shared_data" -> BaseDir.SHARED_DATA;
            // it would be nice to limit this to just ES modules, but we don't have a way to plumb that through to here
            // however, we still don't document in the error case below that shared_repo and shared_data is valid
            case "shared_repo" -> BaseDir.SHARED_REPO;
            default -> throw new PolicyValidationException(
                "invalid relative directory: " + baseDir + ", valid values: [config, data, home]"
            );
        };
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Use "linux", "macos", or "windows" exactly (lowercase).
2. If you want the entry to apply to all platforms, omit the `platform` key entirely rather than passing a sentinel like "all".

Example fix

// before
{ "relative_path": "logs", "relative_to": "home", "mode": "read", "platform": "osx" }

// after
{ "relative_path": "logs", "relative_to": "home", "mode": "read", "platform": "macos" }

private static final Set<String> ALLOWED_PLATFORMS = Set.of("linux", "macos", "windows");
public static void validatePlatform(String p) {
    if (p != null && !ALLOWED_PLATFORMS.contains(p)) {
        throw new IllegalArgumentException("platform must be one of " + ALLOWED_PLATFORMS);
    }
}

public static boolean isValidPlatform(String p) {
    return p == null || Set.of("linux","macos","windows").contains(p);
}

When it happens

Trigger: A files-entitlement entry includes a `platform` key whose value is not in the allowed set (e.g. "osx", "mac", "win", "unix", or "Linux" with wrong casing).

Common situations: Using colloquial OS names (osx/mac) instead of the canonical literal; assuming case-insensitivity; copy-pasting from documentation written for a different schema; mis-typing the platform literal.

Related errors

• 'relative_path' [{}] must be relative
• 'path' [{}] must be absolute
• invalid mode: {}, valid values: [read, read_write]
• invalid relative directory: {}, valid values: [config, data,
• must specify at least one path

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