Skip to content

Commit b3a3605

Browse files
authored
Add breaking change documentation for PackageReference version requirement (#46922)
1 parent ab5d2bb commit b3a3605

File tree

3 files changed

+59
-0
lines changed

3 files changed

+59
-0
lines changed

docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
7878
| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 |
7979
| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 |
8080
| [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md) | Source incompatible | Preview 1 |
81+
| [PackageReference without a version raises an error](sdk/10.0/nu1015-packagereference-version.md) | Behavioral change | Preview 6 |
8182
| [HTTP warnings promoted to errors in `dotnet package list` and `dotnet package search`](sdk/10.0/http-warnings-to-errors.md) | Behavioral/source incompatible change | Preview 4 |
8283

8384
## Windows Forms
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "Breaking change - PackageReference without a version raises an error"
3+
description: "Learn about the breaking change in .NET 10 where PackageReference without a version raises NU1015 error instead of NU1604 warning."
4+
ms.date: 06/23/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/46386
7+
---
8+
9+
# PackageReference without a version will raise an error
10+
11+
Starting in .NET 10, NuGet raises a [`NU1015` error](/nuget/reference/errors-and-warnings/nu1015) when a `PackageReference` item doesn't have a version specified, instead of the previous [`NU1604` warning](/nuget/reference/errors-and-warnings/nu1604).
12+
13+
There's no change when using Central Package Management, since by design the PackageReference XML should not have a version in that scenario.
14+
15+
## Version introduced
16+
17+
.NET 10 Preview 6
18+
19+
## Previous behavior
20+
21+
Previously, NuGet raised a NU1604 warning with the following text:
22+
23+
> Project dependency 'PackageA' does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results.
24+
25+
## New behavior
26+
27+
Starting in .NET 10, NuGet raises a NU1015 error with the following text:
28+
29+
> The following PackageReference item(s) do not have a version specified: PackageA
30+
31+
## Type of breaking change
32+
33+
This is a [behavioral change](../../categories.md#behavioral-change).
34+
35+
## Reason for change
36+
37+
The "no lower bound" message was confusing, and it was unclear how to fix the issue. Additionally, NuGet restored the lowest version for that package, which is rarely what developers want. This change provides clearer and more actionable error messages when the version metadata is missing.
38+
39+
## Recommended action
40+
41+
Add a version to the package reference, for example:
42+
43+
```diff
44+
- <PackageReference Include="Some.Package" />
45+
+ <PackageReference Include="Some.Package" Version="1.2.3" />
46+
```
47+
48+
If the lowest package version is desired, then use `Version="0.0.0"`. In this case, NuGet will raise warning NU1603, rather than the previous NU1604.
49+
50+
To revert to the previous warning, you can set `SdkAnalysisLevel` to `9.0.300` or lower. However, this will affect all features that gate on `SdkAnalysisLevel`.
51+
52+
## Affected APIs
53+
54+
None.

docs/core/compatibility/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ items:
7474
href: sdk/10.0/msbuild-custom-culture.md
7575
- name: NU1510 is raised for direct references pruned by NuGet
7676
href: sdk/10.0/nu1510-pruned-references.md
77+
- name: PackageReference without a version raises error
78+
href: sdk/10.0/nu1015-packagereference-version.md
7779
- name: HTTP warnings promoted to errors in package list and search
7880
href: sdk/10.0/http-warnings-to-errors.md
7981
- name: Windows Forms
@@ -1984,6 +1986,8 @@ items:
19841986
href: sdk/10.0/msbuild-custom-culture.md
19851987
- name: NU1510 is raised for direct references pruned by NuGet
19861988
href: sdk/10.0/nu1510-pruned-references.md
1989+
- name: PackageReference without a version raises error
1990+
href: sdk/10.0/nu1015-packagereference-version.md
19871991
- name: HTTP warnings promoted to errors in package list and search
19881992
href: sdk/10.0/http-warnings-to-errors.md
19891993
- name: .NET 9

0 commit comments

Comments
 (0)