> ## Documentation Index
> Fetch the complete documentation index at: https://dpos.xdr.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose Mirror Manager preparation, HTTP readiness, Phase 1 resume, and DP 6.6.0 bringup problems.

# Troubleshooting

Identify which layer failed before changing anything:

```text theme={null}
Mirror Server configuration
  → Download / prepare
  → HTTP distribution
  → Readiness
  → DP Phase 1 OS upgrade
  → DP Phase 2 bringup
  → Post-upgrade validation
```

## Mirror Manager does not reopen after SSH disconnect

Reconnect and run:

```bash theme={null}
sudo ubuntu-offline-mirror mirror-manager
```

Do not rerun `install.sh` simply to reopen the GUI.

## Download and Prepare was interrupted

Run Menu 2 again after confirming another copy is not already active.

The workflow can reuse completed files and partial data. Do not delete ACPS `.part` files merely to force a clean retry.

Useful checks:

```bash theme={null}
ls -lt /var/log/ubuntu-mirror-automation/
cat /etc/ubuntu-mirror/dp-upgrade-mirror.status
```

## Readiness is NOT READY or FAIL

Recheck in this order:

1. saved Configuration
2. Mirror Server IP
3. prepared artifact status
4. nginx configuration and service state
5. live HTTP access to the files required by the selected mode
6. Menu 4 again

Do not start the DP upgrade until readiness reports `PASS`.

## Mirror Server IP changed

Update the IP in Configuration and run the required sequence again:

```text theme={null}
2 → 3 → 4 → 7
```

Do not reuse old Menu 7 commands because generated client artifacts contain the saved Mirror Server IP.

## Phase 1 OS upgrade is blocked

The current Phase 1 engine distinguishes retryable conditions from integrity or evidence problems.

Transient examples include:

* DNS failure
* HTTP/network failure
* NTP failure
* active apt/dpkg lock

Correct the cause and follow the current status/recovery guidance. Do not delete `/opt/aelladata/os-upgrade` to make the state disappear.

## Ubuntu 22.04 looks unhealthy

Jammy is an intermediate OS state in a Full upgrade. On affected DP builds, the product runtime may be unavailable or incompatible during this hop.

Do not repair kubelet, Docker, or the DP runtime merely to make the intermediate state healthy. Continue the validated OS workflow to Ubuntu 24.04, then complete Phase 2.

## Worker bringup fails

Check:

* the correct DL/DA worker list was saved in Mirror Manager
* master-to-worker SSH reachability
* the configured common `aella` worker password
* node IP addressing and MTU
* NTP and DNS
* Kubernetes node state
* that common staging completed on all nodes before final master orchestration

Regenerate Menu 7 output after any relevant configuration change.

## Rollback

The project does not provide OS or DP-runtime downgrade commands. If a destructive failure cannot be safely recovered using the current release tooling, restore the approved hypervisor snapshot.