Proxy Caching, Negative Cache, Remote Storage, Routing Rules, Repository Health, and Failure Behavior: Diagnostics, Failure Modes, Security, and Performance

1. The diagnostic sequence

flowchart TD
E[Preserve client + HTTP evidence] --> V[Confirm Nexus version / edition / runtime]
V --> C[Inspect client URL + auth + local cache]
C --> T[Inspect repository type / group / routing]
T --> Z[Inspect authorization]
Z --> M[Inspect component / asset / metadata state]
M --> P[Inspect proxy cache / negative cache / remote]
P --> N[Inspect DNS / TLS / outbound HTTP proxy / rate limit]
N --> S[Inspect database / blob / disk / JVM / tasks]
S --> F[Apply smallest controlled fix]
F --> R[Repeat one controlled request]

Keep the order. A 404 caused by a routing rule should not trigger database maintenance; a 401 from remote storage should not trigger client cache deletion; a local Maven cache hit should not be used to prove Nexus recovered.

2. Failure mode: upstream now has it, negative cache still says it does not

This commonly appears with fast internal publishing. Request A returns 404 and Nexus caches absence. The artifact is then published upstream. Request B reaches Nexus before the negative TTL expires and can still return not-found without rechecking.

Correction: on the disposable proxy, use repository Invalidate Cache or wait for the negative TTL. In production, prefer a TTL aligned with publication cadence rather than routine manual invalidation.

3. Intentionally broken example: routing rule blocks a valid public artifact

Create a disposable BLOCK rule whose matcher deliberately catches org/hamcrest/, test it in the rule tester, assign it to the disposable Central proxy, and request org/hamcrest/hamcrest/2.2/hamcrest-2.2.pom. Preserve the exact HTTP status/body returned by your version.

export NX_URL="http://127.0.0.1:8081"
export GROUP_URL="$NX_URL/repository/academy-ch13-public"
export HAMCREST_PATH="org/hamcrest/hamcrest/2.2/hamcrest-2.2.pom"

curl -sS --netrc-file "$NX_AUTH_FILE"   -o "$LAB/evidence/routing-block-body.txt"   -w 'routing-test http=%{http_code} total=%{time_total}
'   "$GROUP_URL/$HAMCREST_PATH"   | tee "$LAB/evidence/routing-block-metrics.txt"

Repair by unassigning or correcting that routing rule only, then repeat the same request. Do not clear blobs, rebuild the search index, restart Nexus, or disable authorization: none of those controls caused the denial.

4. Failure mode: remote credentials expired

There are two authentication hops: client → Nexus and Nexus → remote. A client may successfully authenticate to Nexus while Nexus receives 401/403 from a private upstream. Preserve Nexus logs showing the remote request, check the proxy repository's HTTP Authentication configuration and rotate the remote service-account credential according to the upstream owner's process.

Never paste a real remote password into a curl command for testing. Use protected secret files or the Nexus configuration UI and delete temporary credentials after the drill.

5. Failure mode: DNS, TLS or corporate outbound proxy

6. Failure mode: upstream 429 or service throttling

A rate-limit response means the upstream is protecting capacity. Lowering cache ages, disabling negative cache or multiplying retries can make the condition worse. Preserve the upstream status and headers where available, reduce unnecessary remote churn, verify cache policy and coordinate with the upstream's documented limits.

Do not interpret 429 as a Nexus database problem just because many developers see it simultaneously.

7. Failure mode: client cache hides the server fix

Maven, npm, pip, NuGet and other clients maintain local caches and metadata. After repairing Nexus, a developer may still reproduce the old failure locally. Use a fresh isolated client cache/configuration for verification. That separates “server still broken” from “client reused previous local state.”

For Maven, point a one-off verification command at a temporary local repository rather than deleting the developer's normal ~/.m2/repository. For other ecosystems use the equivalent isolated cache/config option taught in their format chapters.

8. Search index state is not proxy content state

Rebuild Index synchronizes repository content with Nexus search. It does not fetch an upstream component, clear negative cache or repair a TLS failure. Conversely, Invalidate Cache is about proxy freshness and not-found state; it is not a generic search-index repair. Choose the action that owns the failed invariant.

9. Database, blob, disk and JVM checks come later—but still matter

If remote behavior is correct yet writes fail, inspect free disk, blob availability, database latency/read-only state and JVM pressure. A nearly full instance can enter read-only behavior. High blob IO or task load can make cached responses slow even when no upstream request occurs. These symptoms require storage/runtime evidence, not remote TTL changes.

10. Why “invalidate everything” is a poor first response

Invalidating a group can propagate cache effects to member repositories. Broad invalidation also creates an outbound refresh wave on subsequent client requests. Start with the specific disposable proxy or failing path hypothesis. If a single negative entry is the suspected cause and waiting is acceptable, waiting for TTL expiry is often less disruptive than forcing immediate revalidation.

11. Failure-to-control map

12. Knowledge check

13. Summary and next step

You now have a failure map that preserves original evidence and repairs the smallest causal state. Lesson 5 combines the chapter into a controlled checkpoint with predicted state transitions and an auditable evidence packet.

Official references and version notes

• Sonatype: Repository Types.
• Sonatype: Configurable Repository Fields — proxy cache ages, negative cache, blocked and auto-blocking fields.
• Sonatype: Repository Actions — Invalidate Cache, Rebuild Index and HealthCheck actions.
• Sonatype: Routing Rules.
• Sonatype: HTTP Request and Proxy Settings.
• Sonatype: Repository Health Check and Self-Hosted Feature Matrix.
• Sonatype: Securing Nexus Repository — current private-network/SSRF controls for remote URLs.
• Sonatype: Nexus Repository API Reference.
• Sonatype verified Nexus Docker image tags.

Version-sensitive statements were rechecked on 2026-08-26. Sonatype's verified container registry exposes Nexus Repository 3.95.2 as the current latest image line, while the archive-download documentation may lag at 3.94.1. This chapter therefore records the actual running server version as authoritative evidence and uses 3.95.2 only as the concrete current reference baseline. The mandatory work requires Community-compatible proxy repositories, routing rules, cache controls and the Repository Health Check summary only; no Pro-only detailed RHC report, staging, HA, user tokens, export/import or Repository Firewall capability is required.