Troubleshooting version catalog problems
- Accessor name clash
- Too many entries in a single catalog
- Use of a reserved alias name
- Undefined version reference
- Undefined alias reference
- Invalid dependency notation
- Unsupported catalog file format
- Catalog file doesn’t exist
- Invalid alias or bundle notation
- Invalid module notation
- Invalid TOML definition
- Unsupported TOML file format version
- Invalid plugin notation
- Alias not finished
- Too many import invocations
- No import files
- Too many import files
This page summarizes the different problems that Gradle reports when using version catalogs and provides guidance for fixing them.
Accessor name clash
This error indicates that your version catalog contains (at least) two aliases which are mapped to the same accessor.
Given an alias like some.alias
, Gradle implements a mapping strategy to a getter for type-checked accessors.
In this case, it means that two aliases are in conflict because they result in the same getter being created.
To fix this problem, you must choose different aliases.
Too many entries in a single catalog
This error indicates that a version catalog contains too many entries. Because of JVM file format restrictions, when Gradle generates dependency accessors, it has to put an upper limit to the number of aliases that a catalog may contain. This limit is currently of 32000 entries.
To fix this problem, if you need more entries, it’s probably best to split the catalog into multiple, distinct catalogs.
Use of a reserved alias name
This error indicates that you chose an alias which is a reserved name.
Typically this happens if you choose an alias which starts with versions
, bundles
, or plugins
or contains extensions
, convention
, class
, as it may clash with generated accessors.
To fix this problem, you must choose a different alias.
Undefined version reference
This error indicates that your catalog declares a library which references a non-existing version. When you use version references in a catalog, the version reference must point to an existing version alias.
To fix this, you must either:
-
fix the version reference to use one of the versions declared in the catalog
-
or declare a new version corresponding to the reference you want to use in the catalog
It’s worth noting that catalogs are isolated, so you cannot use a version reference from one catalog in another catalog.
Undefined alias reference
This error indicates that your catalog declares a bundle (a group of libraries) which references a non-existing library.
Bundles should only consist of libraries declared in the same catalog.
To fix this, you must either:
-
make sure that the alias for the library you want to include is defined in the same catalog
-
or remove the library from the bundle
Invalid dependency notation
This error indicates that the dependency notation associated with an alias is incorrect.
Version catalog supports the simplified group:artifact:version
notation.
If you are using the Settings
DSL to create a catalog, you can use the to
method in different flavors:
library("some-alias", "com.mycompany:some-lib:1.1").withoutVersion()
// or
library("some-alias", "com.mycompany", "some-lib").version("1.1")
If you are using TOML files to create a catalog, you can use one of the following notations:
[libraries]
some-alias = { group="com.mycompany",
name="some-lib",
version="1.1"
}
# or
some-alias = {
module="com.mycompany:some-lib",
version="1.1"
}
Unsupported catalog file format
This error indicates that you tried to import a catalog file, but the format isn’t recognized.
Typically, this happens if you tried to import a catalog using from(files("some-catalog.txt"))
.
Currently Gradle only supports TOML version catalogs.
To fix this problem, either import a TOML file, or use the Settings
API to declare your catalog.
Catalog file doesn’t exist
This error indicates that you tried to import a catalog file, but the file doesn’t exist.
Make sure that it’s not a typo, and if not, that the catalog file exists before importing it.
Invalid alias or bundle notation
This error indicates that you have used an alias (or bundle) name which isn’t supported by Gradle.
Gradle puts some restrictions on alias names: they must match the following regular expression: [a-z]([a-zA-Z0-9_.\-])+
A typical alias name would be some-alias
.
Invalid module notation
This error indicates that your module notation in a TOML version catalog is incorrect.
When you use the module
notation in a TOML, it must consist of 2 elements, the group
and the name
of the module, separated by a colon (:
).
For example:
[libraries]
groovy = { module="org.codehaus.groovy:groovy", version="3.0.5" }
Invalid TOML definition
This error indicates that you have a syntax or grammar error in your TOML version catalog file.
This can happen if you use wrong keys, for example:
some-alias = { unknownKey = "foo" }
or that you forgot about some elements:
# missing the "group"
some-alias = { name="my-lib", version="1.0" }
Unsupported TOML file format version
This error indicates that you are trying to read a version catalog file which has a higher version than what the current version of Gradle supports.
This would usually mean that the version catalog file you’re trying to use has been produced with a higher release of Gradle than the one you’re using.
A potential solution to this is to upgrade your Gradle version.
Invalid plugin notation
This error indicates that the dependency notation associated with a plugin alias is incorrect.
The TOML version catalog supports the simplified plugin.id:version
notation when declaring a plugin alias.
Therefore this usually means that you have a notation which consists of a string, but which doesn’t separate the plugin id from the plugin version using a semicolon.
Alias not finished
This error indicates that an alias builder was created, but never registered with the catalog. This is usually because
you didn’t call .version()
or .withoutVersion()
on the builder.
The solution is to call whichever version method is appropriate.
Too many import invocations
This error indicates that an import statement (e.g. from(Object notation)) was called more than once.
A version catalog can only be imported from a single source. To prevent the import of multiple sources, some methods will throw an exception when called more than once.
A simple example could be the following, which triggers the error when building a version catalog:
create("testLibs") {
from(files("gradle/a.versions.toml"))
from(files("gradle/b.versions.toml"))
}
When this happens, make sure that there is only a single import invocation per version catalog.
No import files
When an import statement receives a notation, which doesn’t resolve to a file, an exception will be thrown.
A simple example could be the following, which triggers the error when building a version catalog:
create("testLibs") {
from(files())
}
The solution is to make sure that from is not called with empty files.
Too many import files
When an imported file doesn’t resolve to a file, an exception will be thrown.
A simple example could be the following, which triggers the error when building a version catalog:
create("testLibs") {
from(files("gradle/a.versions.toml", "gradle/b.versions.toml"))
}
The solution is to make sure that from is not called with a notation, which resolves into multiple files.