skip to content

What does RepositoriesMode.FAIL_ON_PROJECT_REPOS do, and why would you set it?

level: middleimportance: must knowfreq 50%

answer

  1. fails if any project declares repositories
  2. three modes: PREFER_PROJECT / PREFER_SETTINGS / FAIL_ON_PROJECT_REPOS
  3. PREFER_PROJECT is the default
  4. strict single-source-of-truth enforcement
  5. repositoriesMode.set(...)

basics

~10 s

It makes the build fail if any subproject declares its own repositories {} block, forcing all repositories to come from the central settings.gradle.kts list — making that list the single source of truth.

solid answer

~40 s

`RepositoriesMode.FAIL_ON_PROJECT_REPOS` is a value for `dependencyResolutionManagement.repositoriesMode`. With it set, if **any** `build.gradle.kts` still declares a `repositories {}` block, the build fails fast with an error. You set it to enforce that the centralized settings-level repository list is the *only* place repositories can be declared — giving you guaranteed consistency and a single audit point for security/governance. Contrast it with the default `PREFER_PROJECT` (a project's own repos override the central ones) and `PREFER_SETTINGS` (central repos win and any project-level repos are silently ignored). FAIL_ON_PROJECT_REPOS is the strict, fail-loud option teams use to lock the build down so no module can sneak in an unapproved or insecure repository.

code

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

go deeper

for a junior

Know it makes the build fail if a subproject declares its own repositories.

for a middle

List all three modes, name PREFER_PROJECT as default, and explain why FAIL_ON_PROJECT_REPOS is fail-loud.

for a senior

Discuss it as enforcement for governance/security and call out that plugin-injected repos can break under it.

for a principal

Position it as the enforcement lever for an org-wide dependency-sourcing policy and discuss rollout (migrating modules off project repos).

## What it is `repositoriesMode` is a `Property<RepositoriesMode>` on the `dependencyResolutionManagement` block. The enum `org.gradle.api.initialization.resolve.RepositoriesMode` has three values that decide what happens when both the central (settings) list and a project-level `repositories {}` exist: | Mode | Behavior | |------|----------| | `PREFER_PROJECT` (default) | If a project declares repositories, **its** list is used and the central one is ignored for that project. | | `PREFER_SETTINGS` | The settings/central list is used; any project-level repositories are **silently ignored** with a warning. | | `FAIL_ON_PROJECT_REPOS` | If **any** project declares repositories, the build **fails** with an error. | ## Why FAIL_ON_PROJECT_REPOS The two `PREFER_*` modes silently resolve the conflict, which means drift can creep in unnoticed. `FAIL_ON_PROJECT_REPOS` makes the policy **explicit and enforced**: the only legal place to declare repositories is the central settings block. The first time someone copy-pastes a `repositories {}` into a module, the build breaks and they must move it to settings. This is the option of choice for: - **Security/governance** — guarantees no module can add an unvetted repository (a supply-chain risk). - **Reproducibility** — every module resolves from the same surface. - **Auditability** — one file to review. ## How to set it ```kotlin // settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { mavenCentral() } } ``` ## Gotchas - It only governs `dependencyResolutionManagement` repositories, **not** `pluginManagement` repositories — plugin repos are unaffected. - It applies to the regular project repositories; `buildscript {}` blocks are a separate legacy path. - Some third-party plugins inject project repositories programmatically; under FAIL_ON_PROJECT_REPOS those plugins will cause failures and must be reconfigured.

  • What's the difference between FAIL_ON_PROJECT_REPOS and PREFER_SETTINGS?
    PREFER_SETTINGS silently ignores project-level repositories (with a warning) and uses the central list; FAIL_ON_PROJECT_REPOS hard-fails the build the moment any project declares repositories. The latter is fail-loud, the former is fail-quiet.
  • What is the default repositoriesMode if you set none?
    PREFER_PROJECT — a project's own repositories override the central list for that project.
  • Does this mode also affect plugin repositories?
    No. It only governs dependencyResolutionManagement repositories. Plugin repositories live in pluginManagement and are not subject to this mode.

saying these in an interview costs you the question

  • Saying it forbids declaring repositories anywhere — it forbids them in projects, the central settings block is still required.
  • Claiming it also blocks plugin repositories.
  • Confusing FAIL_ON_PROJECT_REPOS (fails) with PREFER_SETTINGS (silently ignores).

context

resolving links…