Build was configured to prefer settings component metadata r

Error message

Build was configured to prefer settings component metadata rules over project rules but rule '{}' was added by {}

What it means

Companion to the repositories-mode warning: DefaultDependencyResolutionManagement.ruleMutationDisallowedOnProject fires when a project registers a component metadata rule (dependencies.components { ... }, components.withComponentMetadataRules, or rule sources) while dependencyResolutionManagement uses RulesMode.PREFER_SETTINGS. The warning names the rule and the source that added it; under FAIL_ON_PROJECT_RULES the same message is thrown as InvalidUserCodeException instead.

Source

Thrown at platforms/software/dependency-management/src/main/java/org/gradle/internal/management/DefaultDependencyResolutionManagement.java:215

                LOGGER.warn(message);
                break;
            default:
                break;
        }
    }

    private void ruleMutationDisallowedOnProject(DisplayName ruleName) {
        UserCodeApplicationContext.Application current = context.current();
        Describable displayName = current == null ? null : current.getSource().getDisplayName();
        if (displayName == null) {
            displayName = UNKNOWN_CODE;
        }
        String message = "Build was configured to prefer settings component metadata rules over project rules but rule '" + ruleName + "' was added by " + displayName;
        switch (getConfiguredRulesMode()) {
            case FAIL_ON_PROJECT_RULES:
                throw new InvalidUserCodeException(message);
            case PREFER_SETTINGS:
                LOGGER.warn(message);
                break;
            default:
                break;
        }
    }

}

View on GitHub (pinned to 534f27719b)

Solutions

Move the component metadata rule into dependencyResolutionManagement { components { ... } } in settings.gradle(.kts).
Use the rule name in the message to locate the offending declaration (grep the rule class or withModule id).
If project-scoped rules are required, change rulesMode to PREFER_PROJECT or clear the mode.
Remove now-redundant per-project rules after verifying behavior in the settings block.

Example fix

// before — build.gradle.kts (project scope, warns under PREFER_SETTINGS rules mode)
dependencies.components { withModule("com.example:legacy") { belongsTo(...) } }
// after — settings.gradle.kts
dependencyResolutionManagement {
    components { withModule("com.example:legacy") { belongsTo(...) } }
}

Defensive patterns

Strategy: try-catch

Validate before calling

# detect project-scoped component metadata rules before enabling PREFER_SETTINGS rules mode
grep -rn --include='build.gradle*' --include='*.gradle' 'components\.withModule\|dependencies.components\|withComponentMetadataRules' . \
  || echo 'no project-level component metadata rules'

Try / catch

// under FAIL_ON_PROJECT_RULES the same condition throws; catch when applying
// third-party plugins that register metadata rules at project scope
try {
    project.dependencies.components.withModule("com.example:legacy") { /* rule */ }
} catch (e: org.gradle.api.InvalidUserCodeException) {
    logger.warn("metadata rule suppressed by rulesMode: ${e.message}")
}

Prevention

Centralize component metadata rules in dependencyResolutionManagement { components { ... } } in settings.
The warning includes the rule's display name — grep for that name to find the declaring script or plugin.
Migrate rules before switching rulesMode, and use FAIL_ON_PROJECT_RULES temporarily to flush out hidden ones.
Re-check applied convention plugins after upgrades; they may add rules you forgot about.

When it happens

Trigger: settings.gradle declares dependencyResolutionManagement { rulesMode } in PREFER_SETTINGS (or default PREFER_SETTINGS behavior) while a build.gradle contains dependencies.components { withModule(...) { ... } } or a ComponentMetadataRule applied at project scope.

Common situations: Teams hoisting dependency management into settings while legacy per-project metadata rules remain; convention plugins applying metadata rules to every project; merging multi-repo builds into one settings-driven build.

Related errors

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/22c9a5663c1034ef. Report an issue: GitHub.