skip to content

In settings.gradle.kts, what is the required ordering of pluginManagement {}, plugins {}, and other settings code, and why does it matter?

level: middleimportance: must knowfreq 38%

answer

  1. pluginManagement first
  2. then plugins {}
  3. then dependencyResolutionManagement / include
  4. chicken-and-egg: need repos to resolve plugins
  5. error if not first statement

basics

~10 s

pluginManagement {} must come first, then plugins {}, then the rest (rootProject.name, include, etc.). pluginManagement must precede plugins because it tells Gradle where to fetch those plugins from.

solid answer

~40 s

Gradle enforces a strict ordering at the top of `settings.gradle.kts`: `pluginManagement {}` must be the **very first** statement, then the `plugins {}` block, then everything else (`dependencyResolutionManagement {}`, `rootProject.name`, `include(...)`). The reason is causal: `pluginManagement {}` declares the repositories and resolution rules used to fetch the Settings plugins, so it has to be evaluated *before* Gradle tries to resolve the IDs in `plugins {}`. If you put `pluginManagement` after `plugins`, or interleave arbitrary code before it, Gradle fails the build with an error that `pluginManagement {}` must appear as the first block. The `plugins {}` block applying Settings plugins likewise must precede project structure declarations so build-wide config (toolchains, cache, scans) is in place before include logic runs.

code

kotlin · 12 lines
kotlin
// settings.gradle.kts — required order
pluginManagement {
    repositories { gradlePluginPortal() }
}
plugins {
    id("com.gradle.develocity") version "3.18"
}
dependencyResolutionManagement {
    repositories { mavenCentral() }
}
rootProject.name = "my-app"
include("app")

go deeper

for a junior

Remember pluginManagement comes first, then plugins, then the rest.

for a middle

Explain the causal reason: repos must be known before plugin IDs are resolved, and that Gradle enforces it.

for a senior

Distinguish pluginManagement vs dependencyResolutionManagement repositories and note the parser-level requirement.

for a principal

Standardize this prologue in a shared settings convention so all org builds resolve plugins consistently.

## The fixed prologue of settings.gradle.kts Gradle parses the settings script but treats a few blocks specially — they must appear in a fixed order at the top: ```kotlin // 1. FIRST — where plugins & their dependencies are resolved from pluginManagement { repositories { gradlePluginPortal() mavenCentral() } } // 2. SECOND — apply Settings plugins (resolved via the repos above) plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" id("com.gradle.develocity") version "3.18" } // 3. then the rest, in any order dependencyResolutionManagement { repositories { mavenCentral() } } rootProject.name = "my-app" include("app", "core") ``` ## Why pluginManagement must be first `pluginManagement {}` configures **how plugin IDs are resolved**: which repositories to search, plus optional `resolutionStrategy` and `plugins {}` version pinning. Gradle has to know this *before* it can resolve the plugin markers in the subsequent `plugins {}` block. If `pluginManagement` came later, Gradle would already need to have resolved the plugins — a chicken-and-egg problem. So the parser requires it to be the first block; otherwise: ``` org.gradle.api.GradleException: when evaluating settings 'pluginManagement {}' must appear as the first statement ``` ## Why plugins {} comes before project structure Settings plugins applied in `plugins {}` may register toolchain resolvers, configure the build cache, or enable scans. These should be established before `include`/`includeBuild` and dependency-resolution logic so the whole build is consistently configured. Practically, Gradle also requires `plugins {}` to appear before such statements. ## Common mistakes - Putting `println(...)` or a `val` declaration above `pluginManagement {}` — anything but `pluginManagement` first triggers the error. - Confusing the *settings* `pluginManagement.repositories` (for plugins) with `dependencyResolutionManagement.repositories` (for project dependencies). They are separate. ## Mental model Think of it as a dependency chain: *repositories for plugins* → *apply plugins* → *use what they configured* → *declare the build*. The order of the blocks mirrors that chain.

  • What error do you get if pluginManagement {} isn't the first block?
    A GradleException stating that `pluginManagement {}` must appear as the first statement when evaluating settings.
  • Is pluginManagement.repositories the same as dependencyResolutionManagement.repositories?
    No. The former tells Gradle where to fetch plugins; the latter where to fetch project dependencies. They are configured separately.

saying these in an interview costs you the question

  • Saying ordering doesn't matter — Gradle hard-fails if pluginManagement isn't first.
  • Putting plugin repository config inside dependencyResolutionManagement expecting plugins to resolve from it.

context

resolving links…