elastic/elasticsearch · error · GradleException

Usage of deprecated ${className} in ${projectPath}

Error message

Usage of deprecated ${className} in ${projectPath}

What it means

Thrown by RestrictedBuildApiService.failOnUsageRestriction when a Gradle project uses a deprecated/restricted build-API class and that project's path is not on the usageWhitelist for that class. The service is a Gradle BuildService that gates adoption of internal/legacy plugins (currently LegacyRestTestBasePlugin) to a fixed set of grandfathered projects, forcing all new code onto the supported replacement.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/RestrictedBuildApiService.java:63

        map.put(LegacyRestTestBasePlugin.class, ":x-pack:qa:rolling-upgrade-legacy");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:qa:rolling-upgrade-basic");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:plugin:eql:qa:ccs-rolling-upgrade");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:plugin:ml:qa:multi-cluster-tests-with-security");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:plugin:shutdown:qa:rolling-upgrade");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:plugin:transform:qa:multi-cluster-tests-with-security");

        // Projects that inherit the legacy-yaml-rest-test plugin from their parent's subprojects { } configuration.
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:qa:runtime-fields:core-with-mapped");
        map.put(LegacyRestTestBasePlugin.class, ":x-pack:qa:runtime-fields:core-with-search");
        return map;
    }

    public void failOnUsageRestriction(Class<?> aClass, Project project) {
        if (getParameters().getDisabled().getOrElse(false)) {
            return;
        }
        if (isSupported(aClass, project.getPath()) == false) {
            throw new GradleException("Usage of deprecated " + aClass.getName() + " in " + project.getPath());
        }
    }

    private boolean isSupported(Class<?> aClass, String path) {
        return usageWhitelist.get(aClass).contains(path);
    }

    public abstract static class Params implements BuildServiceParameters {
        public abstract Property<Boolean> getDisabled();
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Do NOT silence by disabling the service globally. Instead, migrate the new project to the supported REST test plugin (the modern yaml-rest-test / standalone-rest-test replacement that does not apply LegacyRestTestBasePlugin).
2. If the usage is legitimate and permanent (e.g. a new grandfathered migration qa project), add the project path to the appropriate group in createLegacyRestTestBasePluginUsage() with a comment justifying why migration is not yet possible.
3. To temporarily unblock local exploration, pass -Dorg.elasticsearch.gradle.build-api-restriction.disabled=true (the BUILD_API_RESTRICTIONS_SYS_PROPERTY) — but do not commit reliance on this.

Example fix

// before: new project :x-pack:plugin:foo:qa:rest applies legacy-yaml-rest-test -> fails
// after option A (preferred): use the modern yaml rest test plugin instead
// after option B (last resort, with justification): whitelist it
//   map.put(LegacyRestTestBasePlugin.class, ":x-pack:plugin:foo:qa:rest");

// Before applying a restricted plugin, check the whitelist programmatically:
boolean allowed = usageWhitelist.get(LegacyRestTestBasePlugin.class)
    .contains(project.getPath());
if (!allowed) {
    throw new GradleException(
        "Refusing to apply LegacyRestTestBasePlugin in " + project.getPath()
        + "; migrate to the modern yaml-rest-test plugin.");
}

When it happens

Trigger: failOnUsageRestriction(aClass, project) is called (typically from a plugin-detection hook). If the disabled param is unset/false AND isSupported(aClass, project.getPath()) is false (i.e. usageWhitelist.get(aClass) does not contain the project path), it throws. The whitelist currently maps LegacyRestTestBasePlugin to ~20 specific :x-pack:... and :qa:... paths.

Common situations: A new project applies LegacyRestTestBasePlugin (directly or via legacy-yaml-rest-test/legacy-java-rest-test/standalone-rest-test) but is not in the whitelist; copying a rest-test submodule that inherits the legacy plugin; adding an x-pack qa project without migrating to the new yaml-rest-test setup.

Related errors

• Cannot load VersionPropertiesBuildService
• Cannot resolve minimum compiler version via VersionPropertie
• Elasticsearch version is missing from properties.
• Expected elasticsearch version to be numbers only of the for
• Invalid qualifier: ${qualifier}

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