What causes "Unknown REST API version {}" in elastic/elasticsearch?

Pin the major to 8 or 9, which are the supported versions in this build (see RestApiVersion enum).

elastic/elasticsearch · error · IllegalArgumentException

Unknown REST API version {}

Error message

Unknown REST API version {}

What it means

Thrown by RestApiVersion.forMajor(int) when the requested major version is not one of the explicitly enumerated cases (8 or 9). RestApiVersion only models major REST API versions that Elasticsearch still supports, so any other major — older (<=7) or newer (>=10) in this build — is rejected. This is an API-contract guard, not a network-layer check.

Source

Thrown at libs/core/src/main/java/org/elasticsearch/core/RestApiVersion.java:72

        };
    }

    public static Predicate<RestApiVersion> onOrAfter(RestApiVersion restApiVersion) {
        return switch (restApiVersion) {
            case V_9 -> r -> r.major >= V_9.major;
            case V_8 -> r -> r.major >= V_8.major;
        };
    }

    public static RestApiVersion forMajor(int major) {
        switch (major) {
            case 8 -> {
                return V_8;
            }
            case 9 -> {
                return V_9;
            }
            default -> throw new IllegalArgumentException("Unknown REST API version " + major);
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

Pin the major to 8 or 9, which are the supported versions in this build (see RestApiVersion enum).
If you must handle a broader range, branch on the int before calling forMajor and reject/handle unknown majors explicitly.
For compatibility tests against older majors, use the V_8 constant (minimumSupported) rather than a hard-coded 7.
Regenerate or update version constants if this code was ported from an older branch — the switch only knows current majors.

Example fix

// before
RestApiVersion v = RestApiVersion.forMajor(7); // throws

// after
RestApiVersion v = RestApiVersion.minimumSupported(); // V_8 in this build

Defensive patterns

Strategy: validation

Validate before calling

// Validate a major before calling forMajor
static RestApiVersion safeForMajor(int major) {
    return switch (major) {
        case 8 -> RestApiVersion.V_8;
        case 9 -> RestApiVersion.V_9;
        default -> throw new IllegalArgumentException("Unsupported REST API major " + major);
    };
}

Type guard

static boolean isSupportedMajor(int major) {
    return major == 8 || major == 9; // keep in sync with RestApiVersion enum
}

Try / catch

try {
    RestApiVersion v = RestApiVersion.forMajor(major);
} catch (IllegalArgumentException e) {
    // negotiate or reject the request; do not continue with an unknown version
    throw new BadRequestException("Unsupported API version: " + major);
}

Prevention

Branch on the raw major int before resolving to the enum so unknowns are handled explicitly.
Use RestApiVersion.minimumSupported() / current() instead of hard-coded majors.
When reading a version from a wire format, validate against the enum's supported set.
Update version-aware code when bumping the supported major in RestApiVersion.

When it happens

Trigger: Calling RestApiVersion.forMajor(7), forMajor(10), forMajor(0), or any int outside {8,9} in this source tree. Common in serialization paths that read a major version byte from a stream or header and resolve it to the enum.

Common situations: Reading a versioned wire format or a Compatible-With header (Accept: application/vnd.elasticsearch+json;compatible=7) targeting a major this binary does not model. Cross-version cluster communication where one node is older/newer. A test using a stale major constant.

Related errors

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