# Troubleshooting

Most replication failures are environment issues, not regressions in the paper.
Classify each as **SKIP** (a tool or resource you could not provide) or **FAIL**
(the experiment ran and produced a wrong number). Only a genuine wrong number is a
FAIL.

## Setup and toolchain

- **`uv: command not found`** — install uv (https://docs.astral.sh/uv/). Until then
  the synthetic and real-genome runs are **SKIP**.
- **First `run_all.sh` is slow or downloads a lot** — expected: the six bundles
  seal their environments and download TenSEAL (over Microsoft SEAL) once, then
  reuse them. Not a failure.
- **TenSEAL build fails** — usually a missing C++ toolchain or an unsupported
  platform. This is **SKIP** (a build-environment issue), not a paper regression.

## Real-genome studies (E5-E8)

- **`bcftools: command not found`** — E5-E8 need `bcftools`; without it they are
  **SKIP**. The synthetic evaluation (Section 10) does not need it and should still
  run.
- **Network / IGSR fetch fails or times out** — E5-E8 fetch bounded chr22 intervals
  from the public 1000 Genomes FTP. A network failure is **SKIP**.
- **A study writes only aggregate outputs** — expected and correct: individual
  genotype vectors are kept under an ignored `work/` directory by design.

## Interpreting numbers

- **A synthetic ciphertext size is off by tens of bytes at 192/256-bit** — expected:
  only the 128-bit sizes are byte-deterministic; 192/256-bit sizes drift across
  TenSEAL builds. Check exactness (`max_error == 0`) and the shrinking-size trend,
  not the exact byte count, at those levels. Not a FAIL.
- **A 128-bit ciphertext size differs from `references/expected-results.md`** — this
  IS a **FAIL**; those counts are deterministic.
- **`max_error` is nonzero anywhere** — **FAIL**. The exactness claim is that
  decrypted BFV output equals the plaintext oracle exactly.
- **E8 `r2` = 1.0000 on pair 4** — expected; it is a small-count artifact, not a
  wrong number.

## What a clean PASS looks like

`run_all.sh` prints `RESULT: PASS`, `verify.py` exits zero, all six 128-bit
ciphertext sizes match, `max_error` is 0 everywhere, and the E5-E8 headline numbers
match `references/expected-results.md`.