Artifact Repository Foundations, Package Supply Chains, Components, Assets, and Repository Managers: Diagnostics, Failure Modes, Security, and Performance

1. The diagnostic sequence

flowchart TD
E[Preserve error and request evidence] --> V[Confirm Nexus version edition runtime]
V --> C[Inspect client URL and auth]
C --> R[Inspect format type group routing]
R --> A[Inspect authorization]
A --> S[Inspect component asset metadata]
S --> P[Inspect proxy cache and upstream]
P --> D[Inspect database blob disk]
D --> O[Inspect logs tasks metrics]
O --> F[Apply smallest correction]
F --> T[Controlled retest and verify]

This order deliberately starts outside the server internals. A wrong client URL, wrong repository type, missing privilege, or stale client cache is cheaper and safer to prove than a database/storage theory. Only descend toward database/blob/JVM/storage when higher layers are consistent.

2. Preserve concise evidence before changing anything

mkdir -p evidence/ch01-l4
export NX_URL="http://127.0.0.1:8081"

date -u +%FT%TZ | tee evidence/ch01-l4/time.txt
curl -i "$NX_URL/service/rest/v1/status"   | tee evidence/ch01-l4/status.txt
curl -fsS "$NX_URL/service/rest/v1/repositories"   | tee evidence/ch01-l4/repositories.json   | python -m json.tool

# Capture a failing request without placing a password in the command text.
curl -sS -D evidence/ch01-l4/headers.txt   -o evidence/ch01-l4/body.txt   -w 'http=%{http_code} remote=%{remote_ip} total=%{time_total}\n'   "$NX_URL/repository/does-not-exist/com/example/demo/1.0/demo-1.0.jar"   | tee evidence/ch01-l4/request-summary.txt

Record the exact endpoint, repository name, format expectation, client/tool version, auth method, timestamp, and HTTP status. Sanitize secrets. A 401, 403, 404, 409, 5xx, timeout, checksum mismatch, or client parse error points to different layers; collapsing all of them into “Nexus is broken” destroys information.

3. Failure mode: source commit mistaken for published artifact

Symptom: a deployment ticket says “deploy commit abc123,” but there is no repository coordinate/digest/build record. The team rebuilds later and assumes the new bytes are the same release.

Diagnosis: source identity and artifact identity are different. Rebuilds can vary because dependencies, plugins, build environment, timestamps, base images, generated files, or toolchains differ. Ask for the accepted component coordinate, repository, asset checksum/digest, build ID, and source commit. If those do not exist, the provenance chain was never captured.

Correction: publish once into an authoritative hosted repository, record exact byte identity, and promote/copy the accepted artifact when the process is intended to preserve immutable identity. Do not “fix” traceability by retroactively declaring an arbitrary rebuilt binary equivalent.

4. Failure mode: proxy cache mistaken for authoritative repository

Symptom: an internal library is available today through a proxy, so a team documents the proxy as its release store.

Diagnosis: inspect the repository type. A proxy obtains content from a remote and manages cached state according to remote/cache rules. Ask who owns the upstream, whether Nexus can re-fetch it, how cache cleanup affects it, and whether your organization controls immutability.

Correction: publish organization-owned release artifacts to an intentional hosted repository and expose them through a group if consumers need one same-format URL.

5. Failure mode: successful download mistaken for trust

Symptom: a dependency downloads from Nexus with HTTP 200 and passes a checksum comparison against the bytes Nexus already cached, so it is labeled “approved.”

Diagnosis: separate availability/integrity from trust. HTTP 200 is availability. A matching checksum is byte identity against a reference. Neither tells you whether the reference was trustworthy, the publisher was authorized, the package contains malware, its license is allowed, or its vulnerabilities are acceptable.

Correction: define upstream ownership/routing, publisher controls, verification/provenance, vulnerability/malware/license policy, and incident response as separate layers. Repository Firewall/IQ capabilities may add licensed policy controls, but the conceptual separation applies in Community Edition too.

6. Failure mode: release coordinate overwritten

Symptom: two teams both report com.example:ledger:2.0.0, but their SHA-256 values differ.

Diagnosis: preserve both digests and repository publish history. Check whether a hosted repository allows redeploy, whether CI republished the coordinate, whether clients reached different repositories, and whether one client served local cached bytes. Do not delete either copy to make the evidence “consistent.”

Correction: establish a write-once release policy, separate mutable development repositories, and require artifact digest/build/source evidence before promotion. If compromised credentials may have republished content, rotate/revoke them and investigate access logs/audit evidence appropriate to the environment.

7. Intentionally broken example: publish to the wrong repository type

Create or identify a disposable Maven proxy named academy-maven-proxy only if your training instance is designed for this drill. Then deliberately attempt a component upload to the proxy using the Components API. A proxy is not a producer publication target, so the write must fail rather than become authoritative content.

# This request is intentionally wrong. Use only a disposable training instance.
printf 'synthetic' > demo-1.0.jar

read -r -p 'Disposable Nexus username: ' NX_USER
read -r -s -p 'Disposable Nexus password: ' NX_PASS; echo
NX_AUTH_FILE="$(mktemp)"
chmod 600 "$NX_AUTH_FILE"
printf 'machine 127.0.0.1 login %s password %s
' "$NX_USER" "$NX_PASS" > "$NX_AUTH_FILE"
unset NX_PASS

curl -sS -D evidence/ch01-l4/wrong-type-headers.txt   -o evidence/ch01-l4/wrong-type-body.txt   --netrc-file "$NX_AUTH_FILE"   -X POST "$NX_URL/service/rest/v1/components?repository=academy-maven-proxy"   -F 'maven2.groupId=com.example.academy'   -F 'maven2.artifactId=wrong-target'   -F 'maven2.version=1.0.0'   -F 'maven2.asset1=@demo-1.0.jar'   -F 'maven2.asset1.extension=jar'   -w 'http=%{http_code}\n'

rm -f "$NX_AUTH_FILE"
unset NX_USER NX_AUTH_FILE

Do not memorize one exact 4xx status for every version/recipe. Preserve the response body and then inspect /service/rest/v1/repositories: the target is type: proxy. The root cause is semantic, not “curl syntax.” Correct the target to a disposable Maven hosted repository and retest with the same synthetic coordinate. Then confirm component/assets appear only in the hosted repository.

8. Authorization failures: 401 and 403 are evidence

A 401 typically means the request is not authenticated as required; a 403 means the authenticated principal lacks authorization for the action. Exact client behavior varies, but the diagnostic approach is stable: identify the principal without revealing the secret, list the required repository-view/component privileges for the intended operation, and test the smallest permission change on a disposable account.

Do not solve a publish failure by giving CI administrator privileges. A publisher needs the exact write/browse/read permissions and perhaps upload privilege appropriate to the format/workflow; consumers should generally be read-only. Later security chapters cover roles, realms, tokens, and content selectors deeply.

9. Cache failures: isolate client state before invalidating server state

If a package manager returns an old version, first prove where it came from. Use a disposable client cache/home or direct HTTP/API request. Then inspect Nexus search/assets. If Nexus has stale proxy state, inspect configured cache/revalidation semantics and upstream response before invalidating anything. “Delete every cache” destroys the evidence needed to distinguish layers.

Current 3.95.x release notes contain cache-specific fixes for some ecosystems; this is another reason to record the exact Nexus patch before diagnosing format behavior from memory.

10. Performance diagnosis: one slow download has many possible causes

Sonatype notes Nexus performance is primarily bounded by disk/network I/O rather than CPU in many profiles. That is a starting hypothesis, not permission to ignore CPU or JVM evidence. Measure the failing request under a stated cold/warm cache condition and change one variable at a time.

11. Diagnostic drill and recovery

1. Use a disposable client and intentionally configure a nonexistent Nexus repository URL. Capture the 404/failed request.
2. Correct only the repository name. Do not change credentials, caches, or server state at the same time.
3. If the request then returns 401/403, fix the disposable account's intended access rather than switching to admin.
4. Inspect component/asset state to prove the successful request touched the expected repository.
5. Record what evidence would make you descend to proxy/upstream, database/blob, or JVM/storage investigation.

Cleanup: remove only disposable client files and lab repositories created for the drill. Do not run repair tasks, compact shared blobs, edit database rows, or delete server directories.

Knowledge check

12. Summary

Nexus troubleshooting is a state-location problem. Preserve evidence, confirm version and endpoint identity, inspect repository format/type/routing, authorization, component/asset state, proxy/upstream behavior, then database/blob/JVM/storage only as needed. Apply the least destructive correction and verify with a controlled request.

Official references and version notes

• Nexus Repository 3.95.0–3.95.2 release notes — 3.95.2 was released August 21, 2026 and is the current self-hosted baseline used in this chapter.
• Nexus Repository system requirements — current Java, H2/PostgreSQL, storage, memory, operating-system, and deployment constraints.
• Repository Manager Concepts — components, assets, coordinates, repository formats, proxy behavior, routing, and repository-manager purpose.
• Repository Types — hosted, proxy, and group semantics and group ordering.
• Self-Hosted Nexus Repository Feature Matrix — Community-versus-Pro capability boundaries.
• Nexus Repository API Reference — current REST API surface and embedded Swagger model.
• Status API — readiness and writable-state HTTP checks.
• Search API — component/asset search and the SQL-search behavior used by current releases.
• Components API — listing and uploading components to hosted repositories.
• Assets API — listing and inspecting individual assets.

Version-sensitive statements were rechecked against Sonatype primary documentation on 2026-08-26. The mandatory path remains self-hosted, Community/free-compatible, and disposable; production credentials, production repositories, and paid-only capabilities are outside the lab boundary.