APT, Yum, Raw, RubyGems, Composer, and Operating-System or Generic Artifact Formats: Diagnostics, Failure Modes, Security, and Performance

1. Use one diagnostic sequence across all formats

flowchart TD
E[Preserve client error and request] --> V[Version / edition / recipe support]
V --> U[Client URL and auth]
U --> F[Repository format and type]
F --> P[Privileges / group order / distribution]
P --> M[Native metadata and assets]
M --> C[Proxy cache / client cache / upstream]
C --> S[Database / blob / disk / logs]
S --> X[Least-destructive correction]
X --> R[Fresh controlled request]
R --> E2[Compare evidence]

2. Failure: “the .deb is in Nexus, but apt cannot install it”

Suppose an operator uploaded learner-agent_1.0.0_amd64.deb into a Raw repository and can download it with curl. They then configure APT to treat that Raw URL as a repository. apt update fails because the endpoint lacks the APT distribution/index metadata the client requests.

3. Failure: automation tries to create an APT group

A generic repository-provisioning script assumes every format has hosted/proxy/group recipes. Its APT group request fails because current Nexus does not support APT group repositories.

Repair the automation model, not Nexus. Query the current repository API/recipe support and encode format-specific topology. If one external URL is mandatory, design a supported reverse-proxy/front-door strategy or revisit the requirement.

4. Failure: APT distribution/path mismatch

A proxy or hosted repository is configured for one distribution, while the client's source definition requests another. The resulting 404 or missing Release file may look like an upstream failure.

Evidence should include the exact client source line, Nexus Distribution/Enforce Distribution settings, requested path, and whether the remote is flat. Do not clear every cache before recording the mismatch; the original request path is diagnostic evidence.

5. Failure: Yum hosted rejects an RPM path

A hosted Yum repository can reject an RPM uploaded at a shallower path than its configured Repodata Depth. That is a repository-layout validation failure, not a corrupt RPM. Inspect the configured depth and the proposed asset path. Either use the intended depth or create a repository whose layout matches the package hierarchy.

6. Failure: “make it work” advice disables signature checking

A client rejects repository metadata because the correct public key is not trusted. Disabling repo_gpgcheck, gpgcheck, or APT signature verification globally may make the command continue, but it removes the evidence that protected the supply chain.

Preserve the signature error, identify whether metadata or package verification failed, confirm the expected key fingerprint from a trusted channel, install only that public key, and retest. Never share the private signing key as a client fix.

7. Failure: stale client metadata masks a server correction

APT lists, DNF metadata, Gem caches, Composer caches, Nexus proxy cache, and upstream metadata have different lifetimes. After correcting Nexus configuration, a client may continue using stale local metadata.

8. Failure: private gem unexpectedly comes from public RubyGems

A client still has https://rubygems.org/ configured alongside Nexus. The internal name is not present—or appears later—so the client can contact public infrastructure outside the intended repository boundary.

Inspect gem sources before changing Nexus. For a Nexus-only policy, remove public sources from the disposable configuration or expose the required public content through a Nexus proxy/group. Then verify requests at Nexus and from a fresh client cache.

9. Failure: Composer proxy cannot consume an old v1-only remote

Nexus native Composer support is v2-only. A remote repository that publishes only Composer v1 metadata is not compatible. No amount of cache invalidation or TLS disabling changes the protocol. The correction is to use a v2-compatible upstream or another supported distribution strategy.

10. Failure: Raw group returns the “wrong” same-path file

Raw group repositories do not merge semantic package metadata. If multiple members contain the same path, Nexus checks members in order and returns the first match. This is deterministic but can surprise an operator who expected version arbitration.

Inspect group member order and namespace/path ownership. The correction is usually to eliminate path collisions or order repositories according to an explicit ownership policy.

11. Performance: identify the layer before tuning

12. Intentionally broken example: unsupported APT group assumption

format=apt
type=group
members=internal-apt,ubuntu-proxy
expected=one endpoint for all APT content
actual=recipe/endpoint does not exist in current Nexus

Repair by changing the architecture, not by changing repository internals. The lesson is that automation must be format-aware.

Knowledge check

13. Summary and next step

Most multi-format failures become understandable when you ask which protocol and state layer is wrong. Avoid direct database/blob edits and avoid disabling trust controls. Preserve evidence, identify the format contract, then apply the smallest supported correction.

Lesson 5 combines the chapter into a format-selection and implementation checkpoint.

Official references and version notes

• Sonatype: Formats — current proxy/hosted/group support matrix.
• Sonatype: APT Repositories.
• Sonatype: Yum Repositories and GPG signatures for Yum.
• Sonatype: Raw Repositories.
• Sonatype: RubyGems Repositories.
• Sonatype: Composer Repositories.
• Sonatype: Components API — APT, Raw, and RubyGems upload field names.
• Sonatype: Community/Pro feature matrix and Community Edition onboarding.
• Sonatype: 2026 self-hosted release notes.
• RubyGems command reference, Composer documentation, and distribution-specific APT/DNF/RPM documentation for client trust configuration.

Version-sensitive statements were rechecked on 2026-08-26. The chapter uses Nexus Repository 3.95.0 as the verified feature floor because current Sonatype release notes explicitly list it as released on 2026-08-05 and document Composer hosted/group support there. Some adjacent Sonatype download/version-status pages still lag at 3.94.1, so record the exact version/edition on your lab instance before applying version-specific steps. If you are continuing with a later 3.95.x instance from a prior chapter, it satisfies this chapter's 3.95.0 feature floor. Mandatory labs use Community-compatible RubyGems and Raw features and do not depend on the documentation-sensitive Composer entitlement boundary.