Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Gradle warns that flatDir should be avoided because it has no metadata

ErrorUsing flatDirs should be avoided because it doesn't support any meta-data formats.

Short answer

A flatDir repository is a plain folder of jar or aar files. Gradle gets no POM or Ivy file from it, so it cannot see the library's own dependencies, versions or conflicts. Gradle discourages it. Replace the folder with a Maven repository that uses a local file URL, or publish the library to a real repository.

  • Applies to Gradle 8.x and 9.x, Android Gradle plugin 8.x and 9.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every flatDir declaration. It may be in your own files or added by a plugin or a copied snippet at the project or module level.

    grep -rn "flatDir" --include=*.gradle --include=*.gradle.kts .
  2. 2Match what you see, then jump to its fix

    1. 1The warning appears, and repositories contains flatDir with a folder name such as libsA flatDir repository is declared for local jar or aar filesFix
    2. 2The build succeeds, then the app crashes with a missing class that belongs to a dependency of the aarThe library's own dependencies are missing because there is no POMFix
    3. 3The same library is both in a libs folder and available from a Maven repositoryThe jar is in a flat folder but its POM lives in another repositoryFix

What does the error look like?

  • Using flatDirs should be avoided because it doesn't support any meta-data formats.
  • repositories { flatDir { dirs 'libs' } } in build.gradle
  • NoClassDefFoundError at runtime for a library that an aar in the flat folder needs

Cause 1 of 3

A flatDir repository is declared for local jar or aar files

1Check

Gradle states that flat directory repositories are discouraged because they do not support metadata formats such as Ivy XML or Maven POM files. The build still works, so this is a warning, not a failure.

grep -rn -B2 -A4 "flatDir" --include=*.gradle --include=*.gradle.kts .

2Fix

Binary dependencies should come from an external repository. If that is not possible, Gradle recommends a Maven or Ivy repository that uses a local file URL. Keep the files in a Maven layout inside that folder (group, name, version, plus a .pom file) and point a maven repository at it.

// settings.gradle.kts or build.gradle.kts
repositories {
    maven {
        url = uri("${rootDir}/local-repo")
    }
}

3Verify

Run the build again and check that the warning is gone.

./gradlew assembleDebug

Confirmed by docs.gradle.org

Did this fix it?

Cause 2 of 3

The library's own dependencies are missing because there is no POM

1Check

From a flat folder Gradle only builds basic metadata from the artifact file. Whatever the library depends on is not read, so those libraries are not added for you.

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

2Fix

Publish the library with its .pom into the file-based Maven repository from the previous step, so its dependencies are resolved. Until then, declare the missing dependencies in your own dependencies block by hand.

dependencies {
    implementation("com.example:legacy-lib:1.0.0")
}

3Verify

The dependency report should now list the transitive libraries under the legacy library.

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

Confirmed by docs.gradle.org

Did this fix it?

Cause 3 of 3

The jar is in a flat folder but its POM lives in another repository

1Check

Gradle prefers modules that have real metadata from other repositories, so a flat directory cannot override them. If the jar is in the flat folder and its POM is in another repository, Gradle uses the metadata from the POM.

./gradlew :app:dependencyInsight --dependency legacy-lib --configuration releaseRuntimeClasspath

2Fix

Remove the copy from the folder and the flatDir entry, and let the other repository supply the library.

repositories {
    google()
    mavenCentral()
    // no flatDir
}

3Verify

Run dependencyInsight again; the dependency should come from the remote repository.

./gradlew :app:dependencyInsight --dependency legacy-lib --configuration releaseRuntimeClasspath

Confirmed by docs.gradle.org

Did this fix it?

How do I stop it coming back?

  • Prefer a real repository (a company Maven server or a local file-based Maven repository) for every binary dependency.
  • Do not paste repository blocks from old tutorials into the project without checking them.
  • Keep repositories in one place, the settings file, so unexpected entries are easy to see.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.