NuGet Restore Troubleshooting: Config Inheritance, Source Mapping and Caches

• 1. NuGet merges config files hierarchically
• 2. Make the repo self-contained
• 3. Package source mapping
• 4. Network and proxy
• 5. Clear caches when results look stale

dotnet restore fails with NU1301: Unable to load the service index, or a package restores on your laptop but not in CI. Almost every NuGet restore problem comes down to one question: which nuget.config files are actually in effect? This guide walks through it.

§1. NuGet merges config files hierarchically

NuGet does not read just one file. It walks from the solution directory up to the drive root, then adds the user-level file:

• Windows: %AppData%\NuGet\NuGet.Config
• macOS / Linux: ~/.nuget/NuGet/NuGet.Config

Every file found is merged. A <clear /> inside <packageSources> wipes everything inherited above it.

To see the final result:

dotnet nuget list source

§2. Make the repo self-contained

Put a nuget.config next to the .sln and start with <clear /> so a developer’s personal settings cannot leak in:

<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="internal" value="https://pkgs.example.com/nuget/v3/index.json" />
  </packageSources>
</configuration>

§3. Package source mapping

With more than one source, NuGet may try every source for every package. Source mapping pins patterns to a source, which is faster and safer against dependency confusion:

<packageSourceMapping>
  <packageSource key="nuget.org"><package pattern="*" /></packageSource>
  <packageSource key="internal"><package pattern="Contoso.*" /></packageSource>
</packageSourceMapping>

§4. Network and proxy

NuGet honours HTTP_PROXY / HTTPS_PROXY, and also a config section:

<config>
  <add key="http_proxy" value="http://127.0.0.1:7890" />
</config>

Test the raw endpoint first: curl -I https://api.nuget.org/v3/index.json.

§5. Clear caches when results look stale

dotnet nuget locals all --clear
dotnet restore -v detailed

The detailed log prints every config file path NuGet loaded, which usually reveals the culprit in seconds.

For a step-by-step troubleshooting flow, see NuGet: package sources, config inheritance and restore.

Written by the small team behind Roxi.