Blog

Posted March 23, 2023

How to Prefer settings.gradle Repositories Over build.gradle

Learn how to declare repositories and update your preferred settings to a project repository to avoid getting the error, “Build was configured to prefer settings repositories over project repositories but repository 'XXXX' was added by build file 'build.gradle'.”

Starting with Gradle 7, Android suggests the use of centralized repository declarations in settings.gradle over project- or module-level build.gradle declarations. If you created a new Android project by following the project creation wizard in the latest Android Studio, you will encounter the following error when you try to add a new maven repository in one of your build.gradle scripts:

1
Build was configured to prefer settings repositories over 
2
project repositories but repository 'XXXX' was 
3
added by build file 'build.gradle'

Declaring Repositories in build.gradle

When Gradle tries to resolve the host for one of your java dependencies, it walks through a list of repository urls and checks whether your dependency is hosted there. You can declare this list in your module’s (usually called app or library) build.gradle file the following way.

1
buildscript {
2
    repositories {
3
        google()
4
        mavenCentral()
5
        jcenter() // Warning: this repository is going to shut down soon
6

7
        maven { url 'https://maven.testfairy.com' }
8
        maven { url 'https://example.com/maven' }
9
    }
10
}
11

12
plugins {
13
    id 'com.android.application'
14
}
15

16
...

Alternatively, you can declare the list in your project level build.gradle to enable it for all modules.

1
allprojects {
2
   repositories {
3
       google()
4
       jcenter()
5
       maven { url 'https://maven.testfairy.com' }
6
       maven { url 'https://example.com/maven' }
7
   }
8
}
9
task clean(type: Delete) {
10
   delete rootProject.buildDir
11
}

Unless otherwise specified in settings.gradle, mixing both methods is allowed. However, in cases where the same dependency is hosted by multiple repos in the list, Gradle may attempt to fetch the dependency from the wrong source.

Declaring repositories in settings.gradle

There is a way to enforce a policy for repository declarations. RepositoriesMode api provides the following modes:

FAIL_ON_PROJECT_REPOS: If this mode is set, any repository declared directly in a project, either directly or via a plugin, will trigger a build error.

PREFER_PROJECT: If this mode is set, any repository declared on a project will cause the project to use the repositories declared by the project, ignoring those declared in settings.

PREFER_SETTINGS: If this mode is set, any repository declared directly in a project, either directly or via a plugin, will be ignored.

When a new project is created with Android Studio project creation wizard, FAIL_ON_PROJECT_REPOS will be selected as the default mode. This means all repository declarations must go into settings.gradle file.

1
dependencyResolutionManagement {
2
 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
3
 repositories {
4
   google()
5
   mavenCentral()
6
   jcenter() // Warning: this repository is going to shut down soon
7
   maven { url 'https://maven.testfairy.com' }
8
   maven { url 'https://example.com/maven' }
9
 }
10
}
11
rootProject.name = "ExampleGradle7"
12
include ':app'

How to Fix the “Build was Configured to Prefer Settings Repositories” Error

Build your app and check if one of the errors below occurs.

1
Build was configured to prefer settings repositories over 
2
project repositories but repository 'XXXX' was added 
3
by build file 'build.gradle'
4

5
Could not find any matches for com.testfairy:testfairy-android-sdk:1.+ 
6
as no versions of com.testfairy:testfairy-android-sdk are available.

To fix, make sure you remove the repository declaration from all build.gradle files in the project, including the one in the root project.

Then declare your maven repository in settings.gradle.

Migrating Existing Projects

Add the following configuration to your settings.gradle or replace the current one if it already exists.

1
dependencyResolutionManagement {
2
 repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) // or FAIL_ON_PROJECT_REPOS
3
 repositories {
4
   google()
5
   mavenCentral()
6
   jcenter() // Warning: this repository is going to shut down soon
7
   maven { url 'https://maven.testfairy.com' }
8
   maven { url 'https://example.com/maven' }
9
 }
10
}
11
rootProject.name = "ExampleGradle7"
12
include ':app'