Recovery and Troubleshooting

Describes the recovery and troubleshooting scenarios during the air-gapped repository update operation.

If synchronization fails before the new publication is committed, the previous publication remains active. Correct the reported problem and rerun update with the intended selections. Retain the managed data directory and cache.

If the initial create fails after the serving container has been created, inspect status first. When the managed container is still running, correct the cause and retry synchronization with update. An uninitialized repository can fail readiness checks even though its container is running.

Table 1. Troubleshooting air-gapped repository update
Symptom Action
Runtime unavailable or access denied Confirm Docker or Podman is accessible to the operator and the selected persistent paths are writable.
Container is not running Start the existing managed container before update. If readiness fails because initial content is missing, inspect its running state and correct synchronization before retrying.
Managed container is missing Verify --runtime and any custom --container-name. start does not recreate a removed container. create performs upstream synchronization; it is not an offline serving-only recreation command.
Authentication, TLS, or proxy failure Check the repository root, raw credential values, mode-0600 files, proxy configuration, and required CA. Keep credentials out of shared logs and argv.
Downloader retrieval or interface failure Inspect the reported mapr-setup.sh source and compatibility error. An HTML response or incompatible downloader is not usable package content. See Provide a compatible package downloader for details.
Missing version or OS branch Check upstream package availability and release compatibility. CLI acceptance of an OS selector does not establish product support.
Insufficient space or write failure Check the entire data filesystem, including archives, retained generations, and failed staging. Provide adequate capacity before retrying; do not delete active content or directories during synchronization.
Healthy on host, unreachable from cluster Check DNS, routing, firewall rules, the advertised hostname, host port, and the exact requested branch URL.
Upstream directory returns HTTP 200 but no archives are found A directory listing or HTML response is not evidence that a matching product archive exists. Verify the exact version/OS archive branch and downloader matching rules. Preserve the managed container and cache while correcting the source.
An older runtime rejects empty historical APT indexes Use the matching corrected Airgap CLI/runtime release. The accepted runtime does not impose APT/RPM metadata-content policy. Do not delete or rewrite archived metadata merely to satisfy an obsolete runtime gate.
pub/ is absent in a Core-only or DEP-only mirror This is not an unconditional Airgap publication error. Explicitly synchronize an Installer OS-family branch when the installation workflow needs the signing keys from its archive. Do not manufacture keys or enable unrequested components silently.
Helper updated but serving healthcheck is still old An update --image override replaces neither the running serving container nor its embedded healthcheck. Check the serving image separately; do not assume a synchronization helper update performs a container upgrade.
Publication succeeded but cleanup or a follow-up check failed Inspect the active publication before retrying or cleaning. A failure after the active-link commit does not mean the new publication was rolled back. Retain the cache and avoid deleting active data.