gradle/gradle · error · InvalidUserDataException

Unable to generate an automatic alias for '{}:{}'. Please co

Error message

Unable to generate an automatic alias for '{}:{}'. Please configure an explicit alias for this dependency.

What it means

The auto-generated alias (artifact name with dots replaced by dashes) must match Gradle's alias pattern ([a-z] followed by letters, digits, underscore, dot or dash). If the normalized artifact name starts with a digit, an uppercase letter, an underscore or a dash, or contains other characters, the catalog builder throws InvalidUserDataException because it cannot derive a valid alias.

Source

Thrown at platforms/software/plugins-version-catalog/src/main/java/org/gradle/api/plugins/catalog/internal/DependenciesAwareVersionCatalogBuilder.java:85

    public DefaultVersionCatalog build() {
        if (shouldAmendModel) {
            DependencySet allDependencies = dependenciesConfiguration.getAllDependencies();
            DependencyConstraintSet allDependencyConstraints = dependenciesConfiguration.getAllDependencyConstraints();
            Set<ModuleIdentifier> seen = new HashSet<>();
            collectDependencies(allDependencies, seen);
            collectConstraints(allDependencyConstraints, seen);
        }
        shouldAmendModel = false;
        return super.build();
    }

    void tryGenericAlias(String group, String name, Action<? super MutableVersionConstraint> versionSpec) {
        String alias = normalizeName(name);
        if (containsLibraryAlias(alias)) {
            throw new InvalidUserDataException("A dependency with alias '" + alias + "' already exists for module '" + group + ":" + name + "'. Please configure an explicit alias for this dependency.");
        }
        if (!ALIAS_PATTERN.matcher(alias).matches()) {
            throw new InvalidUserDataException("Unable to generate an automatic alias for '" + group + ":" + name + "'. Please configure an explicit alias for this dependency.");
        }
        library(alias, group, name).version(versionSpec);
    }

    private static String normalizeName(String name) {
        return name.replace('.', '-');
    }

    private void collectDependencies(DependencySet allDependencies, Set<ModuleIdentifier> seen) {
        for (Dependency dependency : allDependencies) {
            String group = dependency.getGroup();
            String name = dependency.getName();
            if (group != null) {
                ModuleIdentifier id = DefaultModuleIdentifier.newId(group, name);
                if (seen.add(id)) {
                    String alias = explicitAliases.get(id);
                    if (alias != null) {
                        library(alias, group, name).version(v -> copyDependencyVersion(dependency, group, name, v));

View on GitHub (pinned to 534f27719b)

Solutions

1. Declare an explicit, pattern-valid alias: catalog { configureExplicitAlias('fast2map', 'com.acme', '2fast2map') }
2. Ensure the explicit alias itself starts with a lowercase letter and uses only [a-zA-Z0-9_.-] afterwards
3. If you control the artifact, publish it under a name starting with a lowercase letter

Example fix

// before
dependencies { versionCatalog 'com.acme:2fast2map:1.0' } // cannot auto-generate alias
// after
catalog { configureExplicitAlias('fast2map', 'com.acme', '2fast2map') }
dependencies { versionCatalog 'com.acme:2fast2map:1.0' }

configurations.versionCatalog.allDependencies.each { d ->
    def alias = d.name.replace('.', '-')
    if (!(alias ==~ /[a-z][a-zA-Z0-9_.\-]+/)) {
        throw new GradleException("Artifact ${d.group}:${d.name} cannot get an automatic alias ('$alias') - declare catalog.configureExplicitAlias")
    }
}

def isValidAlias = { String a -> a ==~ /[a-z][a-zA-Z0-9_.\-]+/ }

When it happens

Trigger: tryGenericAlias runs ALIAS_PATTERN.matcher(alias).matches() on normalizeName(name); it fails for the versionCatalog configuration containing an artifact such as com.acme:2fast2map, com.acme:CommonsText or com.acme:_private, whose normalized names break the leading-lowercase-letter rule.

Common situations: Third-party or legacy libraries with unusual artifact names (version-number prefixes, leading underscore); a new odd-named dependency added to a platform that publishes a catalog; catalog generation that previously worked and now hits one new artifact.

Related errors

• Invalid model name '${name}': it must match the following re
• A dependency with alias '{}' already exists for module '{}:{
• Invalid feature name '{}'. Must match [a-zA-Z0-9]+
• Cannot convert a version catalog entry: '{}' to an object of
• Cannot convert a version catalog entry: '{}' to an object of

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/48b9b3f20c7ac7d8. Report an issue: GitHub.