skip to content

A build fails with 'pluginManagement {} block must appear before any other statements'. What caused it and how do you fix it?

level: juniorimportance: should knowfreq 33%

answer

  1. first non-comment statement
  2. culprit: rootProject.name / include above it
  3. settings plugins resolved via pluginManagement
  4. move block to top
  5. comments/blank lines OK before it

basics

~10 s

Something in settings.gradle.kts comes before the pluginManagement {} block — often rootProject.name, include, or a plugins {} block. Move pluginManagement to the very top of the file.

solid answer

~30 s

This error means a statement was evaluated in the settings file before `pluginManagement {}`. The usual culprits are `rootProject.name = "..."`, an `include(...)`/`includeBuild(...)` call, a settings `plugins {}` block, or even a stray `println`/variable assignment placed above it. Gradle enforces that `pluginManagement {}` is the first thing in the script because plugin resolution must be configured before anything that could trigger it. The fix is simply to move the entire `pluginManagement {}` block to the very top of `settings.gradle.kts`, above all other statements. Comments and blank lines are fine before it; executable statements are not.

code

kotlin · 7 lines
kotlin
// WRONG — triggers the error
rootProject.name = "app"
pluginManagement { repositories { gradlePluginPortal() } }

// RIGHT — pluginManagement first
pluginManagement { repositories { gradlePluginPortal() } }
rootProject.name = "app"

go deeper

for a junior

Recognize the error means a statement precedes pluginManagement; fix by moving it to the top.

for a middle

Explain why Gradle enforces first-position (top-to-bottom evaluation, resolution must be configured first) and where settings plugins go.

for a senior

Tie it to settings plugins and included plugin builds also depending on this ordering, and to keeping a canonical settings layout.

for a principal

Standardize a settings.gradle.kts template across repos so this misordering never recurs in generated or copied builds.

## The error ``` org.gradle.api.InvalidUserCodeException: The pluginManagement {} block must appear before any other statements in the script. ``` ## Why Gradle enforces it The settings file is evaluated **top to bottom**. The plugin-resolution subsystem — repositories, resolution strategy, included plugin builds — has to be fully configured **before** Gradle processes any statement that might need to resolve a plugin (notably a settings `plugins {}` block, or project configuration triggered by `include`). Allowing `pluginManagement` to appear later would mean some resolution could already have happened against an unconfigured subsystem. So Gradle fails fast and deterministically. ## Common causes - A `rootProject.name = "app"` line placed above `pluginManagement {}`. - `include(":core")` or `includeBuild("...")` before it. - A settings-level `plugins {}` block above it (settings plugins are themselves resolved via pluginManagement, so order is critical). - Refactors that accidentally moved a line above the block. - A `dependencyResolutionManagement {}` block placed first. ## The fix Move `pluginManagement {}` to the absolute top: ```kotlin // settings.gradle.kts — correct order pluginManagement { repositories { gradlePluginPortal() mavenCentral() } } plugins { // settings plugins, e.g. id("org.gradle.toolchains.foojay-resolver-convention") version "..." } dependencyResolutionManagement { repositories { mavenCentral() } } rootProject.name = "app" include(":core", ":web") ``` Blank lines and comments above the block are allowed; only **executable statements** before it trigger the error. ## Quick diagnosis checklist 1. Open `settings.gradle.kts`. 2. Confirm `pluginManagement {}` is the first non-comment statement. 3. If a `plugins {}` block exists, it must come *after* `pluginManagement` but typically before `dependencyResolutionManagement`. 4. Re-run the build. This is almost always a five-second fix once you know the rule.

  • Are comments or blank lines allowed before the pluginManagement block?
    Yes. Only executable statements before it trigger the error. Comments and blank lines are fine.
  • If you have a settings plugins {} block, where does it go relative to pluginManagement?
    After pluginManagement. Settings plugins are themselves resolved through pluginManagement, so the resolution config must be established first.

saying these in an interview costs you the question

  • Claiming the block can appear anywhere in settings.
  • Trying to fix it by moving pluginManagement into build.gradle.kts.
  • Thinking comments before it cause the error.

context

resolving links…