skip to content

What does repositoriesMode do inside dependencyResolutionManagement {}, and what is the effect of FAIL_ON_PROJECT_REPOS?

level: middleimportance: must knowfreq 52%

answer

  1. Property<RepositoriesMode>, use .set(...)
  2. PREFER_PROJECT (default)
  3. PREFER_SETTINGS — ignore project repos
  4. FAIL_ON_PROJECT_REPOS — build fails
  5. governance / consistency lever

basics

~10 s

repositoriesMode sets a policy for how per-project repositories {} blocks interact with the centralized ones. FAIL_ON_PROJECT_REPOS makes the build error if any project declares its own repositories, forcing everyone to use the central list.

solid answer

~30 s

`repositoriesMode` is a `Property<RepositoriesMode>` on the `dependencyResolutionManagement {}` block that governs the relationship between the **centralized** `repositories {}` (in settings) and any **per-project** `repositories {}` (in a module's build script). The values are `PREFER_PROJECT` (default — a project's own repos win), `PREFER_SETTINGS` (settings repos win, project repos are ignored with a warning), and `FAIL_ON_PROJECT_REPOS` (the build *fails* if any project declares repositories at all). Teams set `FAIL_ON_PROJECT_REPOS` to enforce that every module resolves only from the approved, centrally-declared repositories — a governance lever that prevents a stray module from pulling from an unvetted source. You set it with `repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)`.

code

kotlin · 11 lines
kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
    }
}

// Now any project that writes:
//   repositories { mavenCentral() }
// in its build.gradle.kts will FAIL the build.

go deeper

for a junior

Know it controls whether modules may declare their own repositories, and that FAIL_ON_PROJECT_REPOS forbids it.

for a middle

List all three enum values, their behaviors, the default, and how to set the Property.

for a senior

Explain the trade-offs and when PREFER_SETTINGS vs FAIL_ON_PROJECT_REPOS is appropriate during migration.

for a principal

Position it as a supply-chain governance control and discuss rollout across many legacy modules that currently declare their own repos.

## The problem it solves In a multi-module build, each `build.gradle.kts` *can* declare its own `repositories {}`. Left unmanaged, modules drift: one pulls from an internal mirror, another from a random public repo, a third forgets entirely. `repositoriesMode` lets the settings author dictate one consistent policy. ## The enum values `RepositoriesMode` has three constants, exposed as a `Property`: - **`PREFER_PROJECT`** — the default. If a project declares its own `repositories {}`, those are used and the settings-level central repositories are ignored *for that project*. Backwards-compatible behavior. - **`PREFER_SETTINGS`** — the centrally declared repositories are always used; any per-project `repositories {}` are silently ignored (Gradle logs that they were skipped). - **`FAIL_ON_PROJECT_REPOS`** — the strictest. If *any* project declares a `repositories {}` block, the build fails fast with an error. This forces all modules to rely solely on the settings-level central declaration. ## How you set it `repositoriesMode` is a lazy `Property`, so you call `.set(...)`: ```kotlin // settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { mavenCentral() } } ``` With this in place, adding `repositories { mavenCentral() }` to a module's `build.gradle.kts` triggers: *"Build was configured to prefer settings repositories over project repositories but repository 'MavenRepo' was added by build file ..."* and the build stops. ## Why FAIL_ON_PROJECT_REPOS is popular It is a *governance* control. Security- and supply-chain-conscious orgs want a single audited place that lists where artifacts may come from. Failing loud (rather than silently ignoring) makes accidental rogue repositories impossible to merge unnoticed. ## Scope note This property is purely the *structural policy* knob on the block. The deeper mechanics of what 'centralized repositories' resolve and how mirroring works are a separate concern; here, focus on the mode's three behaviors and how to set it.

  • What is the default repositoriesMode if you never set it?
    PREFER_PROJECT — per-project repositories {} blocks take precedence over the settings-level central list, preserving legacy behavior.
  • How does PREFER_SETTINGS differ from FAIL_ON_PROJECT_REPOS?
    PREFER_SETTINGS silently ignores project-level repositories (logging a notice) and uses the central ones; FAIL_ON_PROJECT_REPOS hard-fails the build instead of ignoring, so the misconfiguration cannot slip through.
  • Why might an enterprise mandate FAIL_ON_PROJECT_REPOS?
    Supply-chain/security governance: it forces all artifacts to resolve from a single audited, approved repository declaration and makes accidental rogue repositories a build failure rather than a silent risk.

saying these in an interview costs you the question

  • Saying FAIL_ON_PROJECT_REPOS only warns — it fails the build.
  • Assuming the default is FAIL_ON_PROJECT_REPOS (it is PREFER_PROJECT).
  • Setting it like a plain field (e.g. = ) instead of via .set() on the Property.

context

resolving links…