Upgrading a .NET application is usually straightforward until an existing NuGet package stops cooperating.
You update the target framework, install the required SDK, restore the dependencies, and build the solution. Then an older package produces a compatibility warning, a restore error, or a runtime exception. Sometimes the application builds successfully but fails when you run a particular feature.
This is a common challenge in long-running .NET applications. A project may depend on packages introduced years ago, libraries that are no longer maintained, or transitive dependencies that were never updated.
The important thing is not to replace every old package immediately. First, identify what actually broke, understand why it broke, and determine whether the package can safely remain in the application.
In this article, we will use a practical troubleshooting approach for diagnosing NuGet package problems when moving an application to .NET 11.
1. Understand Why an Old Package Can Fail After an Upgrade
A package does not automatically become incompatible just because a new .NET version is released.
NuGet uses target framework information and package assets to determine whether a dependency can be used by a project. A package might contain assemblies for .NET Framework, .NET Standard, or specific versions of .NET.
For example, consider an older class library that supports only .NET Framework 4.7.2. Your application now targets .NET 11. NuGet may not find a compatible assembly for the new target framework.
There are several reasons why this happens:
The package does not support the application's target framework.
The package depends on an older version of another library.
A transitive dependency introduces a version conflict.
The package uses an API that has changed or been removed.
The package depends on platform-specific functionality.
The package is no longer maintained by its author.
The package builds successfully but fails at runtime because of behavioral changes.
It is important to distinguish package compatibility from runtime compatibility.
A package can restore successfully and still fail at runtime. Similarly, a package can be perfectly functional but produce a compatibility warning because its framework support metadata does not explicitly include your target framework.
2. Identify the Package That Is Causing the Problem
The first step is to inspect the dependencies instead of randomly changing package versions.
Run the following command:
dotnet list package
This displays the packages directly referenced by the project.
To include transitive dependencies, run:
dotnet list package --include-transitive
Transitive dependencies are packages installed indirectly through another package.
For example, your application might reference PackageA, which depends on PackageB, which in turn depends on PackageC.
You may never have added PackageC directly, but it can still cause a restore or runtime problem.
For a larger solution, inspect each affected project separately.
You can also use the dependency graph command available in recent .NET 11 SDK builds:
dotnet nuget why . PackageName
Replace PackageName with the package ID you want to investigate.
This command helps explain why a package appears in the dependency graph and which dependency chain introduces it. Check the SDK documentation for availability in the particular SDK build you are using.
For an additional level of detail, inspect the generated obj/project.assets.json file. It contains the resolved package dependencies and framework-specific assets used during restore.
Do not edit this generated file manually. Use it to understand what NuGet resolved.
3. Understand the Most Common NuGet Compatibility Errors
NuGet provides error and warning codes that help identify dependency problems.
The following table covers several messages worth recognizing during an upgrade.
Error or warning | Meaning | What to investigate |
|---|
NU1202 | Package is not compatible with the target framework | Supported target frameworks in the package |
NU1605 | Package downgrade detected | Conflicting dependency version requirements |
NU1701 | Package was restored using fallback framework assets | Whether the selected assets are actually compatible |
NU1703 | Deprecated MonoAndroid package assets are being used | Whether an updated Android-compatible package is available |
These messages do not all describe the same problem.
For example, NU1202 generally indicates that NuGet cannot find compatible package assets for the target framework.
NU1605 is different. It indicates that NuGet resolved a lower package version than another dependency requires.
NU1701 warns that NuGet used assets from a different framework as a compatibility fallback. The application might still compile, but that does not prove that the package will behave correctly.
.NET 11 also introduces an SDK-related change involving NU1703 for packages using deprecated MonoAndroid assets. This is particularly relevant to older mobile projects.
Always investigate the exact warning rather than suppressing it to make the build pass.
4. Fix a Package That Does Not Support the New Target Framework
Consider a project that references an older package:
<ItemGroup>
<PackageReference Include="LegacyDataLibrary"
Version="2.1.0" />
</ItemGroup>
Assume the package supports only older target frameworks and does not provide compatible assets for .NET 11.
The first thing to check is whether a newer version of the package is available.
You can inspect package versions through NuGet Package Manager in Visual Studio or by searching the package on NuGet.org.
If the package author has released a compatible version, update the reference:
<ItemGroup>
<PackageReference Include="LegacyDataLibrary"
Version="3.0.0" />
</ItemGroup>
The version numbers here are illustrative. Use a version that actually exists and whose release notes confirm the required compatibility.
Restore the project:
dotnet restore
Then build it:
dotnet build -c Release
If no compatible package version exists, consider these alternatives:
Contact the package maintainer and request support for the required framework.
Replace the package with a maintained alternative.
Maintain an internal fork if the source is available and your organization can support it.
Create an adapter around the existing functionality and migrate away from the dependency gradually.
Keep the affected project on an older supported target framework temporarily while planning the migration.
Do not use framework fallback settings as a permanent solution without testing. A package that restores through fallback assets is not necessarily safe to use.
5. Resolve Transitive Dependency Version Conflicts
Sometimes the package itself supports .NET 11, but one of its dependencies introduces a conflict.
Consider this example:
MyApplication
├── PackageA 4.0.0
│ └── PackageB >= 4.0.0
│
└── PackageB 3.5.0
PackageA requires PackageB version 4.0.0 or later, but the application directly references version 3.5.0.
NuGet can report NU1605 because its direct-dependency-wins rule allows the application's direct reference to take precedence in the dependency graph.
If the higher version is compatible with the rest of the application, update the direct reference:
<ItemGroup>
<PackageReference Include="PackageA"
Version="4.0.0" />
<PackageReference Include="PackageB"
Version="4.0.0" />
</ItemGroup>
Restore and rebuild the solution.
However, do not blindly increase every dependency to its latest version. A newer dependency can introduce API changes or behavioral differences.
Check the package release notes, dependency requirements, and compatibility information before changing the version.
6. Check Whether the Package Uses an API That Changed
Not every upgrade problem is a NuGet restore issue.
A package might restore and compile correctly but depend on an API whose behavior changed in the new runtime.
.NET 11 includes breaking changes across several areas, including core libraries, networking, cryptography, and SDK behavior.
For example, the .NET 11 breaking-changes documentation describes changes to DateOnly and TimeOnly parsing methods for invalid input. Existing code that relied on the previous behavior may need to be reviewed.
The same principle applies to third-party packages that depend on affected APIs.
When a package fails at runtime, investigate the exception before replacing it.
Useful information includes:
The complete exception message.
The stack trace.
The package version.
The framework target.
The operating system and runtime version.
Whether the issue occurs during application startup or only when a specific method executes.
Also check the official .NET breaking-changes documentation for the affected release.
A package can be compatible at the framework level but still require an update because the underlying API behavior has changed.
7. Use Multi-Targeting to Migrate Without Breaking Everything
Large applications rarely migrate all projects at the same time.
You might have a shared class library used by several applications, including an older service that still targets .NET 10 and a new service targeting .NET 11.
Multi-targeting allows one project to build for both frameworks.
For example:
<PropertyGroup>
<TargetFrameworks>net10.0;net11.0</TargetFrameworks>
</PropertyGroup>
NuGet performs a separate dependency resolution for each target framework.
You can also use conditional package references when different package versions are required:
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
<PackageReference Include="SomeLibrary"
Version="4.0.0" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net11.0'">
<PackageReference Include="SomeLibrary"
Version="5.0.0" />
</ItemGroup>
This approach is useful when the newer package version introduces changes that should not affect the existing .NET 10 application.
However, conditional references should be a temporary migration strategy where possible. Maintaining separate dependency versions increases testing and maintenance requirements.
8. Verify the Fix Before Deploying
A successful restore does not mean the migration is complete.
After updating or replacing a package, verify the application at multiple levels.
Start with a clean restore and build:
dotnet clean
dotnet restore
dotnet build -c Release
Run automated tests:
dotnet test -c Release
Then test the functionality that uses the affected package.
For example, if an older package handles database access, verify connection creation, queries, transactions, and error handling.
If it handles authentication, test token validation, expiration, and authorization behavior.
If it handles file processing, test normal files, empty files, invalid inputs, and larger files.
For production applications, also verify:
Application startup and shutdown.
Dependency injection registration.
Configuration loading.
Logging and diagnostics.
Deployment on the actual operating system.
Performance under realistic workloads.
Any platform-specific behavior.
Finally, review the package's security advisories and maintenance status. A package that works technically may still be unsuitable for production if it has unresolved security issues or no active maintenance.
9. Best Practices for Managing NuGet Dependencies
A .NET upgrade is a good opportunity to improve dependency management.
Consider these practices:
Keep an inventory of direct and transitive dependencies.
Prefer maintained packages with clear framework support.
Review package release notes before major-version upgrades.
Avoid unnecessary direct references to packages already supplied by the shared framework.
Use central package management for consistent versions across larger solutions.
Keep dependency lock files where reproducible restore is important.
Review vulnerability warnings instead of suppressing them.
Test packages on every target framework when using multi-targeting.
Remove unused dependencies rather than carrying them through every upgrade.
For larger solutions, central package management can help keep versions consistent.
For example, create a Directory.Packages.props file:
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>
true
</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="PackageA"
Version="4.0.0" />
<PackageVersion Include="PackageB"
Version="4.0.0" />
</ItemGroup>
</Project>
Projects can then reference these packages without specifying individual versions.
This makes dependency updates easier to review and maintain across multiple projects.
Summary
An old NuGet package stopping work after a .NET upgrade does not always mean the package must be replaced. The actual problem might be an unsupported target framework, a transitive dependency conflict, an API behavior change, or an outdated platform-specific asset.
Start by inspecting the dependency graph, understanding the NuGet error, and checking the package's supported frameworks. Update the package only after reviewing compatibility and release notes. If no suitable version exists, consider replacing it or isolating the dependency while migrating gradually.
A reliable .NET upgrade is not just about getting the solution to compile. It is about making sure every important dependency continues to behave correctly in the new runtime.
Join the conversation! Your thoughts help the community grow.