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

# Troubleshooting

> Solutions for common issues organized by symptom — find your problem and fix it fast.

<Tip>Find your symptom in the sections below. Each issue starts with the quickest fix. If a section says **Known Limitation**, the workaround listed is the best available option.</Tip>

***

## Alignment & Face Detection

<AccordionGroup>
  <Accordion title="The after image looks misaligned — faces don't line up">
    **Most common cause:** Photos taken from different angles, distances, or with different chin positions between sessions.

    **Fix:**

    1. Tap the **face icon** to toggle alignment off, then back on — forces a fresh alignment pass.
    2. If still off, tap **Manual Align** to fine-tune position by hand.
    3. For future photos: use a tripod, mark the patient's floor position, and shoot both sessions from the exact same spot.
  </Accordion>

  <Accordion title="The face is shifted to one side or is off-center">
    **Cause:** The AI uses nose and eye positions to center the image. A slight turn between sessions shifts the centering anchor.

    **Fix:**

    1. Use the **X position slider** in the Crop & Zoom panel to manually re-center.
    2. Use **Manual Align** to lock in a position permanently.
  </Accordion>

  <Accordion title="The face goes off the top or bottom of the frame on initial alignment">
    **Cause:** Most common with close-up shots where the face fills most of the frame.

    **Fix:**

    1. Use the **Y position slider** in the Crop & Zoom panel to bring the face back into frame.
    2. For future photos: leave at least 1–2 cm above the hairline and below the chin.
  </Accordion>

  <Accordion title="Side profile images don't align — one looks higher or more forward">
    **Cause:** At 90°, only nose and mouth are used as anchors. Any difference in chin angle or camera height creates visible misalignment.

    **Fix:**

    1. Use the **Y position slider** to adjust vertical alignment manually.
    2. Use **Manual Align** for full control.
    3. For future profiles: mark the floor with tape and use a wall reference point at nose-tip height.
  </Accordion>

  <Accordion title="Alignment works in the editor but the export looks different">
    **Fix:**

    1. Toggle alignment off, then back on.
    2. If you used Manual Align, tap Reset, then re-apply your adjustments.
    3. Navigate away and back to save the case, then export again.
  </Accordion>

  <Accordion title="One image keeps getting rotated slightly on case open">
    **Cause:** The AI re-runs face detection each time and applies a small corrective rotation based on detected tilt.

    **Fix:** Use **Manual Align**, apply the rotation you want, and save. Manual alignment locks the transform and prevents the AI from recomputing it.
  </Accordion>
</AccordionGroup>

***

## Image Display

<AccordionGroup>
  <Accordion title="A blank / grey panel appears where the image should be">
    **Cause:** The image file for this case may be missing — can happen after reinstalling the app or if the photo was never imported properly.

    **Fix:**

    1. Tap the blank panel to re-import the photo from your library.
    2. If the image was deleted from Photos, you'll need to re-photograph.
    3. Always keep a backup of patient photos in your Photos library or a cloud service — Symetri does not store images in iCloud.
  </Accordion>

  <Accordion title="The image appears rotated (sideways or upside down) after import">
    **Fix:**

    1. Rotate the photo in the iPhone Photos app before importing into Symetri.
    2. Or use the iPhone's native Camera app for clinical photos — it writes orientation correctly.
  </Accordion>

  <Accordion title="The preview looks different from what I see in the editor">
    **Fix:**

    1. Export a test still and review it before presenting to a patient.
    2. If logo or handle is clipped in the export, adjust size or position in Template settings.
  </Accordion>
</AccordionGroup>

***

## Eye Blur

<AccordionGroup>
  <Accordion title="The eye blur is in the wrong position">
    **Cause:** Eye detection failed or AI couldn't find reliable eye positions — often due to hair over the eyes, strong shadows, or extreme angle.

    **Fix:**

    1. Use the **manual position offset sliders** in the eye blur panel to move the blur to the correct location.
    2. For future photos: pull hair away from the face, ensure even lighting across the eye region.
  </Accordion>

  <Accordion title="Only one eye is blurred when both should be">
    **Cause:** The AI detected one eye reliably but not the other — often due to shadow, slight angle, or hair/glasses on one side.

    **Fix:**

    1. Use the position sliders to center the blur between both eyes and increase blur size to cover both.
    2. For future photos: ensure both eyes are equally lit and unobstructed.
  </Accordion>

  <Accordion title="Eye blur disappeared after I edited something else">
    **Cause:** Toggling alignment or changing the treatment profile triggers a pipeline refresh that resets blur to the auto-detected position.

    **Fix:** After any major edit, go back to the Eye Blur panel and confirm position is still correct. Adjust with offset sliders if needed.
  </Accordion>
</AccordionGroup>

***

## Background Removal

<AccordionGroup>
  <Accordion title="Background removal leaves a halo or fringe around the hair">
    **Cause:** Fine hair strands, wispy edges, or backlit hair are difficult for AI segmentation to separate cleanly.

    **Photography fix:** Shoot against a plain, high-contrast background. Avoid backlighting.

    **In-app fix:** Choose a background color close to the original background to blend edge artifacts.
  </Accordion>

  <Accordion title="Background removal doesn't work — background still visible">
    **Cause:** The AI couldn't identify a person, multiple people are in frame, or background color matches the subject's clothing.

    **Fix:**

    1. Ensure only the patient is in frame.
    2. Ensure clothing is a different color from the background.
    3. Toggle background removal off and back on.
  </Accordion>

  <Accordion title="Background removal is very slow">
    **Cause:** Background removal uses an on-device AI model. It can be slow on older iPhones or when the device is under load.

    **Fix:**

    1. Close other apps before running background removal on multiple angles.
    2. Ensure the device is charged above 20%.
    3. **Known Limitation on older hardware** — processing time is significantly longer on iPhone 11 and earlier.
  </Accordion>
</AccordionGroup>

***

## Export & Save

<AccordionGroup>
  <Accordion title="The export button is greyed out">
    **Cause:** Either both images aren't added yet, no export size is selected, or an export is already in progress.

    **Fix:**

    1. Confirm both panels have photos.
    2. Make sure at least one format is checked.
    3. Wait for any active export to finish.
  </Accordion>

  <Accordion title="Export completed but fewer files appeared in Photos than expected">
    **Cause:** Some exports fail silently if a source image is missing or a rendering error occurs.

    **Fix:**

    1. Check which files are missing — re-open that case and re-export that combination.
    2. If a case has missing images (blank panel), re-import the photos before exporting.
  </Accordion>

  <Accordion title="Photo library access denied error">
    **Fix:**

    1. Go to **Settings → Privacy & Security → Photos**.
    2. Find **Symetri** and set access to **Add Photos Only** or **Full Access**.
    3. Return to Symetri and export again.
  </Accordion>

  <Accordion title="The logo doesn't appear on the export">
    **Fix:**

    1. Go to Settings → Clinic Branding and confirm your logo is uploaded.
    2. In the Template panel, confirm the logo toggle is on.
    3. Check logo size — if at minimum, it may be too small to see.
  </Accordion>
</AccordionGroup>

***

## Video Export

<AccordionGroup>
  <Accordion title="Video export fails with an error">
    | Error                                | Fix                                                 |
    | ------------------------------------ | --------------------------------------------------- |
    | "Failed to create pixel buffer pool" | Close other apps, restart Symetri, try again        |
    | "Failed to create pixel buffer"      | Restart the device, then export again               |
    | "Video write failed"                 | Free up storage; check Photos permissions           |
    | "Image conversion failed"            | Re-open case, toggle alignment off/on, export again |
  </Accordion>

  <Accordion title="Video export succeeds but file doesn't appear in Photos">
    **Fix:**

    1. Check device storage — **Settings → General → iPhone Storage**. Free up space if under 1 GB.
    2. Check Photos permissions.
    3. Try exporting a still first to confirm saves are working, then retry video.
  </Accordion>

  <Accordion title="Video export is very slow">
    **Expected behavior:** A typical 3-second slider video at 4:5 takes 10–30 seconds on iPhone 12+. iPhone X and older can take 40–90 seconds.

    **Tips:** Keep the device plugged in, close other apps, avoid exporting while on low battery.
  </Accordion>
</AccordionGroup>

***

## Batch Export

<AccordionGroup>
  <Accordion title="Batch export finishes but fewer files saved than expected">
    **Cause:** Cases missing before or after images are skipped automatically. Rendering failures are also skipped silently.

    **Fix:** Open each failing case individually and confirm both panels have photos before batch exporting.
  </Accordion>

  <Accordion title="Batch export is very slow or app becomes unresponsive">
    **Cause:** Large batches hold all processed images in memory simultaneously.

    **Fix:** Export in smaller batches — select 5–6 cases at a time. Restart Symetri before starting a large batch. Keep the device plugged in.
  </Accordion>

  <Accordion title="Batch export used the wrong template or logo">
    **Cause:** Batch export uses global Settings branding, not per-case settings.

    **Fix:** Before running a batch, go to Settings → Clinic Branding and confirm logo, handle, and placement are correct.
  </Accordion>
</AccordionGroup>

***

## App Performance & Stability

<AccordionGroup>
  <Accordion title="Symetri is slow to open or process images">
    Each case open runs face detection, alignment, and image processing. Give the app 5–10 seconds after opening a case before tapping edit panels. A weekly device restart keeps the system running cleanly.
  </Accordion>

  <Accordion title="Symetri crashes during export or image processing">
    **Most common cause:** Insufficient device memory, especially during batch export.

    **Fix:**

    1. Close all other apps.
    2. Restart the device.
    3. Export fewer cases at a time.
    4. If a specific case consistently crashes the app, re-import photos at standard resolution.
  </Accordion>

  <Accordion title="The app freezes and won't respond">
    **Fix:**

    1. Wait 30 seconds — video export and background removal can appear frozen while processing.
    2. If still frozen, force-close: swipe up from the bottom and swipe the Symetri card up.
    3. Re-open — cases auto-save after each change and should be intact.
  </Accordion>

  <Accordion title="I want to see the walkthroughs again">
    Go to **Settings → How to Use → Replay In-App Walkthroughs** at the bottom of the page. The walkthroughs will appear again the next time you open a case or enter slider mode.
  </Accordion>
</AccordionGroup>

***

## Cases & Data

<AccordionGroup>
  <Accordion title="A case is missing after reinstalling the app">
    **Cause:** Symetri stores all data locally. Deleting the app permanently deletes all case data.

    **Prevention:** Export important cases to your Photos library before deleting the app. Back up your device to iCloud before uninstalling.

    See [Backup & Data Management](/reference/backup-data) for full backup instructions.
  </Accordion>

  <Accordion title="Cases loaded but images are blank after reinstalling">
    **Cause:** Case records were restored from backup but image files may not have been included.

    **Fix:** Re-import photos for each case by tapping the blank panel in the editor.
  </Accordion>

  <Accordion title="I accidentally deleted a case — can I get it back?">
    **No.** Case deletion is permanent and cannot be undone.

    **Prevention:** Export the case to your Photos library before deleting.
  </Accordion>
</AccordionGroup>

***

## Quick Fix Reference

| Symptom                      | First thing to try                              |
| ---------------------------- | ----------------------------------------------- |
| Images misaligned            | Toggle alignment off, then on                   |
| Face off-center              | Adjust X/Y position sliders                     |
| Face off-frame               | Use Y slider; check source photo framing        |
| Eye blur in wrong spot       | Use manual offset sliders in Eye Blur panel     |
| Background removal has halos | Reshoot on plain neutral background             |
| Export button greyed out     | Confirm both before & after images are imported |
| Export missing files         | Check disk space; check Photos permissions      |
| Video export error           | Restart app; close other apps; retry            |
| App crash during batch       | Export fewer cases at a time; restart device    |
| Case images blank            | Re-import photos; check if app was reinstalled  |
| White edges when panning     | Increase zoom before panning                    |
| Walkthroughs not showing     | Settings → How to Use → Replay Walkthroughs     |