Gradle version catalog "Unresolved reference: libs" in CI

By Daniel Zoghalchali·Latchkey

Type-safe version catalog accessors like libs.widgets are generated from a declared catalog (libs.versions.toml). When the catalog is not declared in settings, or the alias does not exist, the Kotlin DSL reports an unresolved reference and the build fails to configure.

What this error means

Configuration fails with "Unresolved reference: libs" or "Unresolved reference: widgets" pointing at a libs.* accessor in a build script.

e: build.gradle.kts:7:20: Unresolved reference: libs
> Script compilation error:
    Line 7:   implementation(libs.widgets)

Common causes

The catalog is not declared in settings

The default libs catalog requires gradle/libs.versions.toml or an explicit versionCatalogs {} entry in settings.gradle.kts; without it the libs accessor is never generated.

The alias name does not match the catalog

TOML aliases map dashes and dots to nested accessors; a mismatch between the alias key and the libs.* reference leaves it unresolved.

How to fix it

Declare the catalog and matching alias

1. Add gradle/libs.versions.toml with the library alias.
2. Reference it with the generated accessor that matches the alias name.
3. Re-run so Gradle regenerates the type-safe accessors.

# gradle/libs.versions.toml
[libraries]
widgets = { module = "com.example:widgets", version = "1.4.0" }

Confirm the settings reference the catalog

If the file is not at the default path, declare it explicitly in settings so the libs accessor exists.

dependencyResolutionManagement {
  versionCatalogs { create("libs") { from(files("gradle/libs.versions.toml")) } }
}

How to prevent it

• Keep the catalog at the default gradle/libs.versions.toml path.
• Match libs.* accessors to the alias keys in the TOML.
• Run a configuration-only build to catch unresolved accessors early.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation