# Troubleshooting

## Docker or Compose Is Unavailable

Run:

```bash
docker version
docker compose version
```

If missing, run:

```bash
./install.sh
```

## ARM64 Image Cannot Run

Running ARM64 images on x86_64 requires binfmt/qemu:

```bash
docker run --rm --privileged tonistiigi/binfmt --install arm64
docker run --rm --platform linux/arm64 debian:bookworm-slim uname -m
```

Expected output: `aarch64`.

## First Snapshot Times Out

All-five snapshot can be slow, especially under QEMU. Increase timeout:

```bash
./start.sh --timeout-secs 14400
```

## Output Counts Are Too Low

Check:

```bash
grep LIVE_TA_REFRESH_BEFORE_SNAPSHOT .env
ls -l /var/lib/ours-rp-arm64/state/live-ta
tail -100 /var/lib/ours-rp-arm64/logs/live-ta-refresh-*.log
```

In `file-live-ta` mode, snapshot should wait until live TA refresh succeeds.

## Grafana Login Fails

Check `.env`:

```bash
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin
```

If Grafana has already started, changing `.env` may not reset the existing Grafana database. Stop services and back up/clean `${HOST_DATA_DIR}/grafana` if needed.

## A Finite Acceptance Test Starts an Extra Run

If `.env` sets a finite `MAX_RUNS=3` while `SOAK_RESTART_POLICY=unless-stopped`, Docker Compose restarts the soak container after it exits successfully.

For finite tests, set:

```bash
SOAK_RESTART_POLICY=no
```

## How to Confirm a Periodic Forced Snapshot

Check the latest run metadata:

```bash
latest="$(find ${HOST_DATA_DIR}/runs -maxdepth 1 -type d -name 'run_*' | sort | tail -1)"
jq '{run_id,sync_mode,snapshot_reason,periodic_snapshot_delta_count,periodic_snapshot_forced,reset_db_cleanup_status}' "$latest/run-meta.json"
```

For a threshold-triggered reset you should see:

- `sync_mode: "snapshot"`
- `snapshot_reason: "periodic_snapshot_delta_limit"`
- `periodic_snapshot_forced: true`

To confirm delta counting still advances after retained runs are pruned, also inspect:

```bash
jq '{last_success_snapshot,successful_deltas_since_snapshot,recent_runs_count:(.recent_runs|length)}' \
  "${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```

## Lifecycle State File Is Corrupt

The script backs up the corrupt file before best-effort bootstrap from retained runs:

```bash
ls -1 "${HOST_DATA_DIR}/state"/run-lifecycle-state.json.corrupt.*
jq . "${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```