elastic/elasticsearch · error · GradleException

Usage of deprecated in

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.

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");
Defensive patterns

Strategy: validation

Validate before calling

// 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.");
}

Prevention

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

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

Appendix: 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)