gradle/gradle · error · IllegalArgumentException

Version cannot be null

Error message

Version cannot be null

What it means

Inside a repository content { } block, includeVersion(group, moduleName, version) (and excludeVersion) validate all three arguments; this message appears when version is null (group and module nulls fail earlier with their own messages). The version string (a selector such as 1.+ also works) is required to build the matcher, so Gradle throws IllegalArgumentException.

Source

Thrown at platforms/software/dependency-management/src/main/java/org/gradle/api/internal/artifacts/repositories/DefaultRepositoryContentDescriptor.java:134

        return copy;
    }

    @Nullable
    private static ImmutableList<SpecMatcher> createSpecMatchers(@Nullable Set<ContentSpec> specs) {
        ImmutableList<SpecMatcher> matchers = null;
        if (specs != null) {
            ImmutableList.Builder<SpecMatcher> builder = ImmutableList.builderWithExpectedSize(specs.size());
            for (ContentSpec spec : specs) {
                builder.add(spec.toMatcher());
            }
            matchers = builder.build();
        }
        return matchers;
    }

    private static void checkNotNull(@Nullable String value, String message) {
        if (value == null) {
            throw new IllegalArgumentException(message);
        }
    }

    @Override
    public void includeGroup(String group) {
        checkNotNull(group, "Group cannot be null");
        addInclude(group, null, null, MatcherKind.SIMPLE);
    }

    @Override
    public void includeGroupAndSubgroups(String groupPrefix) {
        checkNotNull(groupPrefix, "Group prefix cannot be null");
        addInclude(groupPrefix, null, null, MatcherKind.SUB_GROUP);
    }

    @Override
    public void includeGroupByRegex(String groupRegex) {
        checkNotNull(groupRegex, "Group regex cannot be null");

View on GitHub (pinned to 534f27719b)

Solutions

1. Pass a concrete version or selector: includeVersion 'com.example', 'my-module', '1.0'
2. For 'any version of this module', use includeModule 'com.example', 'my-module' instead of a null version
3. Default or validate the value at the source before the content block runs

Example fix

// before
content { includeVersion 'com.example', 'my-module', project.findProperty('pinnedVersion') } // null

// after
content { includeVersion 'com.example', 'my-module', (project.findProperty('pinnedVersion') ?: '1.0') }

def version = project.findProperty('pinnedVersion')
if (version == null) throw new GradleException('pinnedVersion is required for includeVersion')
repositories { maven { content { includeVersion 'com.example', 'my-module', version } } }

// Kotlin DSL
fun requireVersion(value: String?): String =
    checkNotNull(value) { "Version cannot be null" }

When it happens

Trigger: content { includeVersion 'com.example', 'my-module', version } where the version variable or property is unset; reading the triple from a config map missing the version key.

Common situations: Pinning a repository to one version where the version comes from an optional gradle.properties entry; generated content filters where the version field was not populated; builds that intend 'any version' (use includeModule instead).

Related errors

• Group cannot be null
• Group prefix cannot be null
• Group regex cannot be null
• Module name cannot be null
• Module name regex cannot be null

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