{"record":{"id":"48b9b3f20c7ac7d8","repo":"gradle/gradle","slug":"unable-to-generate-an-automatic-alias-for","errorCode":null,"errorMessage":"Unable to generate an automatic alias for '{}:{}'. Please configure an explicit alias for this dependency.","messagePattern":"Unable to generate an automatic alias for '(.+?):(.+?)'\\. Please configure an explicit alias for this dependency\\.","errorType":"exception","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"platforms/software/plugins-version-catalog/src/main/java/org/gradle/api/plugins/catalog/internal/DependenciesAwareVersionCatalogBuilder.java","lineNumber":85,"sourceCode":"    public DefaultVersionCatalog build() {\n        if (shouldAmendModel) {\n            DependencySet allDependencies = dependenciesConfiguration.getAllDependencies();\n            DependencyConstraintSet allDependencyConstraints = dependenciesConfiguration.getAllDependencyConstraints();\n            Set<ModuleIdentifier> seen = new HashSet<>();\n            collectDependencies(allDependencies, seen);\n            collectConstraints(allDependencyConstraints, seen);\n        }\n        shouldAmendModel = false;\n        return super.build();\n    }\n\n    void tryGenericAlias(String group, String name, Action<? super MutableVersionConstraint> versionSpec) {\n        String alias = normalizeName(name);\n        if (containsLibraryAlias(alias)) {\n            throw new InvalidUserDataException(\"A dependency with alias '\" + alias + \"' already exists for module '\" + group + \":\" + name + \"'. Please configure an explicit alias for this dependency.\");\n        }\n        if (!ALIAS_PATTERN.matcher(alias).matches()) {\n            throw new InvalidUserDataException(\"Unable to generate an automatic alias for '\" + group + \":\" + name + \"'. Please configure an explicit alias for this dependency.\");\n        }\n        library(alias, group, name).version(versionSpec);\n    }\n\n    private static String normalizeName(String name) {\n        return name.replace('.', '-');\n    }\n\n    private void collectDependencies(DependencySet allDependencies, Set<ModuleIdentifier> seen) {\n        for (Dependency dependency : allDependencies) {\n            String group = dependency.getGroup();\n            String name = dependency.getName();\n            if (group != null) {\n                ModuleIdentifier id = DefaultModuleIdentifier.newId(group, name);\n                if (seen.add(id)) {\n                    String alias = explicitAliases.get(id);\n                    if (alias != null) {\n                        library(alias, group, name).version(v -> copyDependencyVersion(dependency, group, name, v));","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/gradle/gradle/blob/534f27719b66953f95cc907aae7f2c1b12f5482d/platforms/software/plugins-version-catalog/src/main/java/org/gradle/api/plugins/catalog/internal/DependenciesAwareVersionCatalogBuilder.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Declare an explicit, pattern-valid alias: catalog { configureExplicitAlias('fast2map', 'com.acme', '2fast2map') }","Ensure the explicit alias itself starts with a lowercase letter and uses only [a-zA-Z0-9_.-] afterwards","If you control the artifact, publish it under a name starting with a lowercase letter"],"exampleFix":"// before\ndependencies { versionCatalog 'com.acme:2fast2map:1.0' } // cannot auto-generate alias\n// after\ncatalog { configureExplicitAlias('fast2map', 'com.acme', '2fast2map') }\ndependencies { versionCatalog 'com.acme:2fast2map:1.0' }","handlingStrategy":"validation","validationCode":"configurations.versionCatalog.allDependencies.each { d ->\n    def alias = d.name.replace('.', '-')\n    if (!(alias ==~ /[a-z][a-zA-Z0-9_.\\-]+/)) {\n        throw new GradleException(\"Artifact ${d.group}:${d.name} cannot get an automatic alias ('$alias') - declare catalog.configureExplicitAlias\")\n    }\n}","typeGuard":"def isValidAlias = { String a -> a ==~ /[a-z][a-zA-Z0-9_.\\-]+/ }","tryCatchPattern":null,"preventionTips":["Check artifact names against the alias pattern before adding them to the catalog configuration","Prefer artifact names starting with a lowercase letter when you publish your own libraries","Remember dots are converted to dashes; uppercase after the first char is allowed, digits at the start are not"],"tags":["version-catalog","gradle","alias","naming","validation"],"backgroundTag":"invalid-identifier-characters","analyzedSha":"534f27719b66953f95cc907aae7f2c1b12f5482d","analyzedAt":"2026-08-22T08:09:12.375Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}