dotnet restore fails in CI with NU1301 or 401 Unauthorized against a private NuGet feed, but works on your machine. How do you diagnose and fix it?

1. How restore finds sources and credentials

 repo/nuget.config            \
 repo/../nuget.config          |  merged, closest file first;
 (each parent folder up        |  <clear /> discards every source
  to the drive root)           |  defined in files further up
 ~/.nuget/NuGet/NuGet.Config   |  user level   (developer laptops only)
 machine-wide config          /   machine level (old self-hosted agents)
        |
        v
 effective: packageSources + packageSourceMapping + packageSourceCredentials
        |
        v
 for each package id --> only the source(s) its mapping allows
        |
        v
 GET <source>/v3/index.json (service index)
        |
        +-- network, DNS, proxy or TLS failure --> NU1301
        +-- 401 / 403 --> ask credential providers:
        |       1. packageSourceCredentials in config (can use %ENV_VAR%)
        |       2. Azure Artifacts credential provider
        |          (NuGetAuthenticate task, VSS_NUGET_EXTERNAL_FEED_ENDPOINTS)
        |       3. stored credentials (Visual Studio, interactive sign-in)
        |       none work --> 401 / NU1301
        v
 search for the id and version --> not found --> NU1101 / NU1102 / NU1103
        |
        v
 download .nupkg --> verify hash and signature --> ~/.nuget/packages

Every box on that path behaves differently on a developer laptop and a clean CI agent. That is the whole story behind "works on my machine".

2. Error codes and what to check

3. Local versus CI, side by side

A restore can succeed locally without contacting the feed at all, because every package is already in the global packages folder. CI is the honest test of what the repository declares.

4. A diagnosis routine

1. Read the exact code and the source name in the message.
2. Run dotnet restore -v detailed (or -v diag) in the pipeline. It lists the config files it read, the sources it used and each HTTP call.
3. Run dotnet nuget list source in the repo folder, locally and in CI, and compare.
4. Reproduce CI locally with a clean state: dotnet nuget locals all --clear (or a fresh container) and no user-level config, for example docker run --rm -v "$PWD:/src" -w /src mcr.microsoft.com/dotnet/sdk:10.0 dotnet restore.
5. Check authentication: did the authenticate step run before restore, does the token have read scope, and does the identity have feed permissions?
6. Check network: can the agent resolve and reach the feed host? Is a corporate proxy or TLS inspection in the way?

5. Authenticating CI the supported way

Tokens should be short-lived and read-only. Workload identity federation or the platform's built-in identity is better than a long-lived personal access token.

6. Package source mapping and dependency confusion

 Without source mapping:                    With source mapping:
 Contoso.Abn requested                      Contoso.Abn requested
   -> NuGet asks EVERY source                 -> pattern Contoso.* -> contoso feed ONLY
   -> an attacker has published a             -> nuget.org is never asked for it
      package called Contoso.Abn on
      nuget.org                              the internal package is always used
   -> if the range floats (1.*), the
      attacker publishes a higher
      version, or publishes the exact
      version you use, restore can take
      the public one
   -> the attacker's build logic runs on
      your CI agent

Without mapping, NuGet doesn't treat any source as authoritative for a package id, so the outcome depends on versions and which source answers. Source mapping makes the source for each package explicit. With mapping in place, NU1101 for an internal package often means the pattern doesn't cover it, so check patterns before anything else. An internal Azure Artifacts feed with upstream sources for nuget.org gives a single controlled entry point and keeps a copy of every public package you use.

7. Lock files

Commit the lock files and use locked mode in CI, so a new package version or a compromised feed can't change what you build without a reviewed commit.

8. Caches

dotnet nuget locals all --clear is a diagnostic step to rule out a corrupt cache, not a fix for configuration or authentication problems.

9. NuGet Audit

Restore checks packages against known vulnerability data and reports NU1901 to NU1904. With the .NET 10 SDK, projects targeting .NET 10 or later audit transitive packages by default (NuGetAuditMode is all); older target frameworks audit direct references only unless you set it. Run dotnet list package --vulnerable --include-transitive for a full report, and treat high and critical findings as errors on main branches.

10. Security

• Never commit passwords or tokens in nuget.config.
• Use read-only, short-lived credentials from the platform; restrict who can publish to internal feeds.
• trustedSigners in nuget.config can require signatures from specific repositories or authors.
• Treat restore as the front door of the supply chain: source mapping, a controlled internal feed with upstreams, lock files and audit together close most attack paths, in line with Essential Eight guidance on restricting privileges and patching applications.

11. .NET 11 awareness

NuGet ships with the SDK, so audit defaults and source mapping features can change between SDK versions. Read the NuGet release notes when you move to the .NET 11 SDK.

12. Try it yourself

1. Add the nuget.config from the code example to a solution and run dotnet restore -v detailed; find the list of config files and sources in the output.
2. Run the same restore in a clean SDK container and compare.
3. Add a package whose id isn't covered by any mapping pattern and read the error.
4. Enable lock files, restore, change a version, and run dotnet restore --locked-mode to see NU1004.
5. Run dotnet list package --vulnerable --include-transitive.
6. Point a source at a URL that doesn't exist and read the NU1301 message.

Repo-level nuget.config with explicit sources and source mapping (no credentials committed):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/internal/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Directory.Build.props enabling lock files:

<Project>
  <PropertyGroup>
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>

Azure DevOps pipeline steps:

steps:
  - task: UseDotNet@2
    inputs:
      useGlobalJson: true
  - task: NuGetAuthenticate@1
  - script: dotnet restore Orders.slnx --locked-mode
    displayName: Restore

Diagnostics:

dotnet restore -v detailed          # shows config files, sources and why a package failed
dotnet nuget list source            # effective sources for this folder
dotnet nuget locals all --list      # cache locations
dotnet list package --vulnerable --include-transitive