Diagnosing NuGet Version Conflict Errors in .NET Solutions

Recognizable condition

When building a solution you see errors such as:

NU1107: Version conflict detected for Newtonsoft.Json. Reference the package directly from the project to resolve this conflict.

Unable to find version 12.0.3 of package Newtonsoft.Json.

These messages indicate that two or more projects in the solution are requesting incompatible versions of the same NuGet package.

Short cause/diagnostic table

Project	Requested version	Transitive dependencies (if any)	Effective version chosen by NuGet
ProjectA	Newtonsoft.Json 12.0.3	-	12.0.3 (if resolved alone)
ProjectB	Newtonsoft.Json 13.0.1	-	13.0.1 (if resolved alone)

The resolver cannot satisfy both requests simultaneously, so it fails and reports a conflict.

Ordered checks

1. Identify the conflicting package and projects
   • Open the build output or run dotnet restore --verbosity detailed from the solution root.
   • Look for lines that contain "Conflict" or "Version conflict detected" and note the package name and the versions mentioned.

   Permissions: Read access to the solution folder; no elevated rights needed.

   Risk: The command only reads package metadata; it does not modify files.

2. List each project’s explicit version request
   • For SDK‑style projects, inspect <PackageReference> elements in .csproj files.
   • For packages.config projects, open the file and note the <package> entries.

   Record the version each project asks for.

3. Check transitive dependencies
   • Run dotnet list package in each project folder to see which versions are pulled in indirectly.
   • Alternatively, examine the generated obj/project.assets.json file after a restore attempt; the dependencies section shows resolved versions.

   Note: If a project does not directly reference the package but depends on another package that does, the transitive version will appear here.

4. Determine the effective version NuGet would pick
   • If you temporarily allow a version range (e.g., <PackageReference Include="Newtonsoft.Json" Version="[12.0.3,13.0.1]" />) and run restore, the resolver will choose the highest compatible version within the range.
   • Observe the warning or success message to see which version is selected.

   Caution: This step is diagnostic only; do not commit the range to source unless you intend to use it.

Fixes tied to findings

1. Align explicit requests via Directory.Build.props

If all projects should use the same version, add a central version definition:

<Project>
  <PropertyGroup>
    <NewtonsoftJsonVersion>13.0.1</NewtonsoftJsonVersion>
  </PropertyGroup>
</Project>

Place this file in the solution root. Then in each project reference the package without a version:

<PackageReference Include="Newtonsoft.Json" />

During restore, MSBuild will substitute the property, forcing a uniform version.

2. Use a global.json to lock the SDK and enforce a version

For solutions that rely on the .NET CLI, a global.json can pin the SDK version, which indirectly affects how NuGet evaluates version ranges.

{
  "sdk": {
    "version": "6.0.400"
  }
}

Place this file alongside the solution. Then run dotnet restore again; the restored packages will be evaluated with the pinned SDK’s NuGet behavior.

3. Enforce a single version with <PackageVersion> in Directory.Build.props

If you prefer to keep explicit <PackageReference> versions but want to override them, use:

<ItemGroup>
  <PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
</ItemGroup>

This forces NuGet to treat the requested version as a minimum and will upgrade any lower request to 13.0.1, eliminating the conflict.

4. Accept a version range (only when appropriate)

When the API surface is stable across the conflicting versions, you can allow a range:

<PackageReference Include="Newtonsoft.Json" Version="[12.0.3,13.0.1]" />

Verify that your code does not rely on features introduced or removed between the versions. Run the full test suite after the change.

Escalation criteria

• If the conflict persists after applying the above fixes, check for transitive conflicts where a third‑party package pulls in a different version of the same dependency.
• Examine the obj/project.assets.json file; look for sections under dependencies that show multiple versions of the same package under different parent packages.
• In such cases, consider:
• Updating the third‑party package to a version that aligns with your chosen version.
• Using a <ExcludeAssets> or <PrivateAssets> directive to isolate the conflicting dependency (advanced, requires thorough testing).
• If no compatible version exists, you may need to **refactor** code to avoid the newer/older API or maintain two separate builds with different package sets (e.g., via solution folders and conditional restoration).

Limitations and practical verification

The described approach works for SDK‑style projects and legacy packages.config projects that are restored via dotnet restore or Visual Studio’s NuGet client. It does not apply to projects that use Paket or other dependency managers.

To confirm that a fix succeeded:

1. Run dotnet restore --verbosity minimal and ensure no "Version conflict" warnings appear.
2. Build the solution: dotnet build --configuration Release. The build should complete without NU1107 or similar errors.
3. Open obj/project.assets.json for any project and verify that the package appears with a single version under dependencies.

If warnings remain, repeat the ordered checks to identify any remaining divergent requests.