NuGet Repositories, API Keys, Feeds, Symbols, Proxying, and .NET Package Workflows: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: preserve evidence before changing anything

Use the same sequence as earlier chapters: preserve concise evidence → confirm Nexus version/edition/runtime → inspect client URL/auth → inspect repository type/group members → inspect authorization → inspect package/component/assets → inspect proxy/cache/upstream → inspect database/blob/disk → inspect logs/tasks/metrics → apply the least destructive correction → verify with a controlled request.

flowchart TD
  E[Preserve command + HTTP evidence] --> V[Version / V2-V3 endpoint]
  V --> A[Credentials + repository privilege]
  A --> R[Hosted / proxy / group routing]
  R --> M[Package metadata + assets]
  M --> C[Client cache / Nexus cache / upstream]
  C --> S[DB / blob / disk / logs]
  S --> F[Smallest safe fix]
  F --> T[Fresh controlled restore or push]

2. Broken example: V3 group root without index.json

Intentionally configure the source as http://127.0.0.1:8081/repository/academy-ch10-group/ rather than ending in /index.json. Preserve the restore error. Current Sonatype documentation warns this can trigger V2 auto-detection and a protocol mismatch, especially with group repositories, producing an error such as 502.

WRONG="http://127.0.0.1:8081/repository/academy-ch10-group/"
RIGHT="http://127.0.0.1:8081/repository/academy-ch10-group/index.json"

curl -sS -o /dev/null -w 'wrong root HTTP=%{http_code}
' "$WRONG"
curl -sS -o /dev/null -w 'v3 index HTTP=%{http_code}
' "$RIGHT"

The correction is the V3 service-index URL—not clearing blobs or changing the database.

3. 401 versus 403: authentication and authorization are different

4. Invalid API key after regeneration

Regenerating the key intentionally invalidates earlier keys. If CI starts failing after rotation, do not regenerate repeatedly. Confirm which secret version the runner received, which deployment identity is used, whether the NuGet API-Key Realm is active, and whether the repository privileges still match the target hosted repository.

A stale key is authentication state. It does not imply package corruption or blob loss.

5. Duplicate package/version is not a cache problem

With Disable redeploy, pushing an existing ID/version is expected to fail. Nexus currently returns HTTP 400 for this duplicate case; --skip-duplicate expects a different status and is not a reliable way to turn immutable-release rejection into success.

Fix the release process by publishing a new version. Do not change the repository to Allow redeploy merely to make the build green.

6. Source ambiguity and missing Package Source Mapping

If several client-visible sources are configured and the same ID exists on more than one, restore source selection may be nondeterministic. First inspect the effective NuGet.Config hierarchy. Then use a fresh packages folder and verbose restore. Package Source Mapping can make eligible sources explicit.

If an internal package resolves publicly, treat that as a supply-chain incident signal. Do not solve it by repeatedly clearing caches without correcting the routing policy.

7. Stale client cache versus stale Nexus proxy metadata

dotnet nuget locals all --list
# For the disposable lab only:
rm -rf "$LAB/internal-cache" "$LAB/http-cache"
mkdir -p "$LAB/internal-cache" "$LAB/http-cache"

If the fresh client still sees stale public metadata, inspect Nexus proxy cache ages and remote health. If Nexus has fresh metadata but the client does not, focus on the client cache/config. Do not conflate the two.

8. HTTP/TLS mismatch on modern .NET SDKs

.NET/NuGet increasingly enforces HTTPS by default. For this loopback-only lab, allowInsecureConnections="true" must be explicit. In production, the fix is HTTPS with a trusted certificate—not disabling TLS certificate validation.

NU1302 or related HTTP-source failures on .NET 10 are therefore security configuration evidence, not repository corruption.

9. Symbol failure: check version and content before repair tasks

If .snupkg publication or /symbols retrieval fails, confirm Nexus is 3.95 or newer, the package and symbols were pushed to the intended repository, the symbol package matches the binary build, and the client is using a V3 workflow where required. Only then consider repair guidance.

The current Repair - Rebuild NuGet symbol index task is a Pro repair tool. Do not present it as a Community prerequisite or run it casually during normal operation.

10. Proxy upstream outage or rate limit

A cached package may continue restoring while uncached packages fail. Check proxy remote status, auto-blocking, upstream HTTP code, metadata cache age, and whether the requested package is already cached. This is why “one restore succeeded” does not prove upstream health.

11. Performance: locate the slow layer before tuning

12. Controlled verification request

After any correction, use a new disposable NUGET_PACKAGES folder and the exact intended NuGet.Config. Re-run one pinned restore. For publication changes, use a new synthetic version such as 1.0.1-labfix rather than mutating 1.0.0.

Knowledge check

13. Summary

NuGet incidents become tractable when you preserve the exact source URL, protocol version, source name, auth mechanism, repository type, package ID/version, cache state, and symbol context. Chapter 10's checkpoint now combines those observations into one reproducible evidence packet.

Official references and version notes

• Sonatype: NuGet Repositories — hosted/proxy/group, V2/V3, authentication, Chocolatey, and symbol-server support.
• Sonatype: Configure NuGet With Nexus and NuGet CLI Usage.
• Sonatype: Realms — NuGet API-Key Realm.
• Sonatype: Tasks — current NuGet symbol-index repair task and maintenance cautions.
• Microsoft: NuGet.Config reference and Package Source Mapping.
• Microsoft: authenticated feeds — NuGetPackageSourceCredentials_* environment variables.
• Microsoft: dotnet nuget push and symbol packages (.snupkg).
• Microsoft: NuGet HTTPS Everywhere.
• Microsoft: .NET 10 downloads.

Version-sensitive statements were rechecked on 2026-08-26. The mandatory lab assumes a disposable self-hosted Nexus Repository Community Edition 3.95.2 instance, Java 21 on the Nexus side, and .NET 10 SDK 10.0.400 on the client side. The NuGet symbol/Chocolatey features used here were introduced in Nexus 3.95.0. Record the actual dotnet --info and Nexus version in evidence before execution.