// Copyright 2025 Gradle and contributors.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.
// You may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[version-catalog-problems]]
= How to Troubleshoot Version Catalog Problems in Gradle

Version catalogs help manage dependencies efficiently, but sometimes errors occur.

This guide provides quick solutions to common version catalog issues in Gradle.

[[accessor_name_clash]]
== 1. Fixing Accessor Name Clashes

**Error:** Two aliases in your version catalog map to the same accessor.

[source,toml]
----
someAlias = { module="org.sample:lib", version="1.0" }
some-alias = { module="org.sample:other-lib", version="2.0" }
----

**Solution:** Choose distinct alias names to avoid conflicts.

[source,toml]
----
firstAlias = { module="org.sample:lib", version="1.0" }
secondAlias = { module="org.sample:other-lib", version="2.0" }
----

[[too_many_entries]]
== 2. Handling Too Many Entries in a Catalog

**Error:** The catalog exceeds the 32,000 entry limit imposed by the JVM file format.

**Solution:** Split your catalog into multiple smaller catalogs.

[[reserved_alias_name]]
== 3. Resolving Reserved Alias Names

**Error:** An alias uses a reserved name like `versions`, `bundles`, `plugins`, `extensions`, or `class`.

[source,toml]
----
versions = { module="org.sample:lib", version="1.0" }
----

**Solution:** Choose a different alias name.

[source,toml]
----
sampleLib = { module="org.sample:lib", version="1.0" }
----

[[undefined_version_reference]]
== 4. Fixing Undefined Version References

**Error:** A library references a non-existent version in the catalog.

[source,toml]
----
[libraries]
myLib = { module="org.sample:lib", version.ref="undefinedVersion" }
----

**Solution:** Either correct the reference or declare the missing version in the catalog.

[source,toml]
----
[versions]
definedVersion = "1.0"

[libraries]
myLib = { module="org.sample:lib", version.ref="definedVersion" }
----

[[undefined_alias_reference]]
== 5. Fixing Undefined Alias References

**Error:** A bundle references a library that does not exist in the catalog.

[source,toml]
----
[bundles]
myBundle = ["existingLib", "undefinedLib"]
----

**Solution:** Ensure the library is defined in the catalog or remove it from the bundle.

[source,toml]
----
[bundles]
myBundle = ["existingLib"]
----

[[invalid_dependency_notation]]
== 6. Correcting Invalid Dependency Notation

**Error:** An alias has an incorrect dependency notation.

**Solution:** Use the correct syntax:

[source,groovy]
----
library("some-alias", "com.mycompany:some-lib:1.1").withoutVersion()
----

[source,toml]
----
[libraries]
some-alias = { module="com.mycompany:some-lib", version="1.1" }
----

[[unsupported_file_format]]
== 7. Fixing Unsupported Catalog File Formats

**Error:** An invalid catalog file format (e.g., `.txt`) was used.

**Solution:** Use a TOML file or the `Settings` API.

[[catalog_file_does_not_exist]]
== 8. Handling Missing Catalog Files

**Error:** The specified catalog file does not exist.

**Solution:** Ensure the file exists before attempting to import it.

[[invalid_alias_notation]]
== 9. Correcting Invalid Alias or Bundle Notation

**Error:** The alias name does not match the required format (`[a-z]([a-zA-Z0-9_.\-])`).

[source,toml]
----
Alias! = { module="org.sample:lib", version="1.0" }
----

**Solution:** Use a valid alias name such as `some-alias`.

[source,toml]
----
valid-alias = { module="org.sample:lib", version="1.0" }
----

[[invalid_module_notation]]
== 10. Fixing Invalid Module Notation in TOML

**Error:** Incorrect `module` notation in the version catalog.

**Solution:** Use the correct format:

[source,toml]
----
[libraries]
groovy = { module="org.codehaus.groovy:groovy", version="3.0.5" }
----

[[toml_syntax_error]]
== 11. Resolving Invalid TOML Syntax

**Error:** Syntax or grammar issues in the TOML file.

**Solution:** Ensure correct keys and structure:

[source,toml]
----
some-alias = { group="my-lib", name="1.0" }
----

[[unsupported_format_version]]
== 12. Handling Unsupported TOML File Versions

**Error:** The catalog file uses a version unsupported by your Gradle installation.

**Solution:** Upgrade Gradle to a newer version.

[[invalid_plugin_notation]]
== 13. Fixing Invalid Plugin Notation

**Error:** The plugin alias notation does not separate the plugin ID from the version.

**Solution:** Use the correct format: `plugin.id:version`.

[source,toml]
----
[plugins]
spring-boot = { id="org.springframework.boot", version="2.5.2" }
----

[[alias_not_finished]]
== 14. Resolving Unfinished Aliases

**Error:** An alias was created but not registered in the catalog.

**Solution:** Call `.version()` or `.withoutVersion()` to complete the alias.

[source,groovy]
----
library("some-alias", "org.sample:lib").version("1.0")
----

[[too_many_import_invocation]]
== 15. Fixing Multiple Import Invocations

**Error:** An import statement was called more than once.

**Solution:** Ensure each version catalog has a single import invocation.

[[no_import_files]]
== 16. Handling Missing Import Files

**Error:** The import statement references a file that does not exist.

**Solution:** Ensure the specified file is available before import.

[[too_many_import_files]]
== 17. Fixing Too Many Import Files

**Error:** The import statement references multiple files.

**Solution:** Ensure only a single file is specified for import.

[[invalid_toml_definition]]
== 18. Resolving Invalid TOML Definitions

**Error:** A TOML table contains a key that is not allowed at that location (e.g. an unknown attribute on a library or version declaration).

**Solution:** Remove the unexpected key, or use one of the keys allowed by the surrounding table (such as `group`, `module`, `name`, `version` for a library declaration).

[[invalid_version_notation]]
== 19. Correcting Invalid Version Notation

**Error:** A version string uses syntax that cannot be parsed (for example, the strict version modifier `!!` was placed without a base version before it).

**Solution:** Place a valid version number before the `!!` modifier, e.g. `1.0!!`, or remove the modifier when it is not needed.
