User Interface, Search, Browse, Components, Assets, Tags, Uploads, and Repository Navigation: Diagnostics, Failure Modes, Security, and Performance

Diagnostic preflight

This lesson intentionally diagnoses the disposable academy-ch03-hosted repository and 1.0.0 component created in Lesson 2. If that lab state is absent, complete Lesson 2 first or reproduce its disposable setup; never substitute a production repository. Re-create only the temporary credential file locally, then prove the expected lab objects exist before engineering failures.

LAB="$HOME/nexus-ch03-lab"
NX_URL="http://127.0.0.1:8081"
mkdir -p "$LAB/evidence" "$LAB/payload"
umask 077
read -rsp "Disposable Nexus admin password: " NX_PASS; printf "\n"
printf 'machine 127.0.0.1 login admin password %s\n' "$NX_PASS" > "$LAB/nexus.netrc"
unset NX_PASS
NETRC="$LAB/nexus.netrc"

# Never commit or print $NETRC. Delete it when the lab ends.

curl -fsS "$NX_URL/service/rest/v1/status" | tee "$LAB/evidence/19-status.txt"
curl --fail-with-body --silent --show-error --netrc-file "$NETRC"   "$NX_URL/service/rest/v1/repositories/academy-ch03-hosted"   | tee "$LAB/evidence/19-repository.json"
curl --fail-with-body --silent --show-error --netrc-file "$NETRC"   "$NX_URL/service/rest/v1/search?repository=academy-ch03-hosted&group=com.example.academy&name=ui-demo&version=1.0.0"   | tee "$LAB/evidence/19-component.json"

Stop if the target repository is missing, is not the disposable Maven hosted lab repository, or the synthetic coordinate is absent. The rest of the lesson relies on this known-safe state.

1. Diagnostic sequence

flowchart TD
  E[Preserve concise evidence] --> V[Version edition runtime]
  V --> U[Client URL and authentication]
  U --> R[Repository name type routing]
  R --> P[Authorization]
  P --> M[Component asset metadata]
  M --> C[Proxy cache and upstream if relevant]
  C --> D[Database blob disk]
  D --> L[Logs tasks metrics]
  L --> F[Least destructive correction]
  F --> Q[Controlled verification request]

Use the sequence even when the UI makes the symptom look obvious. An empty Search result can be query semantics or permission filtering; a 404 can be a wrong repository/path; a 403 can be authorization; a 400/405 during upload can be the wrong repository type; a conflict can be deliberate write policy. Database or blob manipulation belongs near the end only when evidence points there and an official recovery procedure requires it.

2. Failure mode: “Search cannot find it”

First prove the direct repository URL and Assets/Components API state. Then test the exact SQL-search fields. Since 3.88.0, keyword tokenization and wildcard behavior differ from old Elasticsearch-based tutorials. Quoting "ui-demo" can require an exact phrase; a positional wildcard may work in fields where supported while format-specific fields have stricter rules.

curl --fail-with-body --silent --show-error --netrc-file "$NETRC" \
  "$NX_URL/service/rest/v1/search?repository=academy-ch03-hosted&group=com.example.academy&name=ui-demo" \
  | tee "$LAB/evidence/20-search-correct.json"

# Deliberately wrong coordinate: expected empty items, not a storage repair signal.
curl --fail-with-body --silent --show-error --netrc-file "$NETRC" \
  "$NX_URL/service/rest/v1/search?repository=academy-ch03-hosted&group=com.example.academy&name=ui-dmeo" \
  | tee "$LAB/evidence/20-search-wrong-name.json"

If the correct exact-coordinate query works, no index repair is justified. If Search fails while Components/Assets/direct retrieval prove content exists, then inspect current search documentation, caller privileges and logs before considering the documented rebuild-index endpoint—and only on the disposable repository after preserving evidence.

3. Failure mode: upload to the wrong repository type

Nexus accepts component upload only to hosted repositories. Do not infer “repository exists” means “repository accepts publication.” Before uploading, retrieve repository details and check type. If a group/proxy is selected, correct the destination rather than changing its purpose.

Chapter 04 will engineer hosted/proxy/group topology; here the essential diagnostic is type recognition.

4. Intentionally broken example: duplicate release coordinate

Chapter 02/03 deliberately configured academy-ch03-hosted with ALLOW_ONCE. Re-run a 1.0.0 upload and preserve the response:

# Preserve the original response instead of hiding it.
set +e
curl --silent --show-error --netrc-file "$NETRC" \
  -D "$LAB/evidence/21-redeploy-headers.txt" \
  -o "$LAB/evidence/21-redeploy-body.txt" \
  -w 'http=%{http_code}\n' \
  -X POST "$NX_URL/service/rest/v1/components?repository=academy-ch03-hosted" \
  -F maven2.groupId=com.example.academy \
  -F maven2.artifactId=ui-demo \
  -F maven2.version=1.0.0 \
  -F maven2.asset1=@"$LAB/payload/ui-demo-1.0.0.jar" \
  -F maven2.asset1.extension=jar \
  | tee "$LAB/evidence/21-redeploy-status.txt"
RC=$?
set -e
printf 'curl_exit=%s\n' "$RC" >> "$LAB/evidence/21-redeploy-status.txt"

The exact status/body can vary by version and request details, but the causal interpretation should be stable: the coordinate already exists under a write-once policy. The wrong fix is changing the repository to allow redeploy just because the pipeline expects success. Verify the original asset checksum is unchanged, then publish a new version when bytes legitimately change.

5. Failure mode: browse works, download or upload does not

Later chapters will create least-privilege roles. For now, diagnose with a small authorization matrix and compare the same controlled request under the intended lab identity versus the disposable administrator.

6. Failure mode: “the UI and API disagree”

Capture the exact component ID, asset ID, repository name and query. The UI may show only the first 300 search results and Browse has its own presentation limit. APIs paginate with continuation tokens. An automation that ignores pagination can falsely report “missing content” while the UI finds it, or vice versa.

Also remember uploader metadata visibility became privilege-controlled in newer releases. Absence of one UI/API field can be an authorization outcome rather than evidence that upload provenance metadata was never recorded.

7. Performance: identify the waiting layer

Do not “tune heap” because Search feels slow. Capture version/runtime, database mode, repository type, operation, request size and timings; then change one causally relevant variable.

8. Least-destructive verification

curl --fail-with-body --silent --show-error --netrc-file "$NETRC" \
  "$NX_URL/service/rest/v1/search?repository=academy-ch03-hosted&group=com.example.academy&name=ui-demo&version=1.0.0" \
  > "$LAB/evidence/22-after-diagnosis-search.json"

curl --fail-with-body --silent --show-error --netrc-file "$NETRC" \
  "$NX_URL/repository/academy-ch03-hosted/com/example/academy/ui-demo/1.0.0/ui-demo-1.0.0.jar" \
  -o "$LAB/evidence/22-after-diagnosis.jar"
sha256sum "$LAB/evidence/22-after-diagnosis.jar" \
  > "$LAB/evidence/22-after-diagnosis.sha256"

A controlled read proves the correction without mutating more content. Preserve the before/after evidence together so the failure is explainable later.

Knowledge check

9. Summary

The same visible symptom can originate in query semantics, repository type, privileges, write policy, pagination, database/search state, blob IO or network behavior. Preserve evidence, classify the layer, and make the smallest correction.

Official references and version notes

• Download Nexus Repository — the official download page used to pin the same 3.94.1-06 self-hosted lab baseline as Chapter 02 while current indexes are rechecked before execution.
• Browsing Repositories — browse-tree behavior, 10,000-component-per-level UI limit, HTML view, and browse/read privilege distinctions.
• Searching for Components — current UI search behavior, first-300-result display, SQL-search semantics, tokenization, exact phrases, and wildcard rules.
• Search API — component/asset search endpoints and continuation-token pagination.
• Viewing Component Information — component identifiers and the relationship to associated assets.
• Viewing Asset Information — asset path, content type, size, blob timestamps/reference, checksums, uploader metadata, and format-specific attributes.
• Uploading Components — hosted-only UI upload boundary and required upload/browse/read privileges.
• Components API — list/get/delete components and format-specific multipart component upload.
• Assets API — paginated asset listing, asset details, paths, download URLs and checksums.
• Repositories API — repository inventory and format/type-specific repository configuration endpoints.
• Privileges — current browse, read, add, edit, delete and search privilege semantics.
• Tagging and Self-Hosted Feature Matrix — component tagging is currently a Pro feature; mandatory Chapter 03 work does not require it.

Version-sensitive statements were rechecked against Sonatype primary documentation on 2026-08-26. The mandatory path remains self-hosted, Community/free-compatible and disposable. The chapter keeps the Chapter 02 lab baseline at Nexus Repository 3.94.1-06 because Sonatype's current download and versions-status pages still present 3.94.1 as the current downloadable/GA line; learners are told to re-check those pages before running the lab.