Skip to content

Troubleshooting

Fix SnapByFace startup and performance problems: missing model files, the NumPy fallback when FAISS is absent, macOS Gatekeeper, Windows SmartScreen, and slow indexing.

Start with the log file — most problems are visible there:

# macOS
open ~/.snapbyface/logs/snapbyface.log

# Windows (PowerShell)
notepad "$env:USERPROFILE\.snapbyface\logs\snapbyface.log"

“Model files missing” when a scan starts

Symptom: the app opens, but starting an analysis fails with a model path error.

  1. Incomplete installation. The package is about 300 MB because det_10g.onnx and w600k_r50.onnx ship inside it. Re-download and reinstall.
  2. Running from the wrong place (macOS). Drag the app to Applications instead of running it from inside the .dmg.
  3. Antivirus quarantine. Some endpoint tools strip large binaries out of app folders — add an exception and reinstall.

:::note SnapByFace never downloads models at runtime. If models are missing, the fix is always to reinstall the package. :::

Slow matching: FAISS fell back to NumPy

SnapByFace searches embeddings with FAISS. If FAISS is not present in the build, it falls back to a NumPy brute-force search.

  • The results are identical. This is a speed difference, not a quality difference.
  • It is most noticeable with tens of thousands of indexed faces.
  • Reinstalling the current build restores FAISS.

:::tip If you cannot reinstall right away, reduce the work instead: index one folder at a time, or adjust the threshold — a threshold change re-matches existing embeddings and never re-analyzes media. See Threshold Tuning. :::

macOS: “SnapByFace is damaged and can’t be opened”

This is Gatekeeper, not a corrupt download. SnapByFace is made by a solo developer and is not notarized yet — Apple’s notarization requires an expensive certificate I have not obtained. Verify the SHA-256 checksum on the download page to confirm the file is genuine, then clear the quarantine attribute:

xattr -cr /Applications/SnapByFace.app
  1. If it still refuses to start, confirm the app sits in /Applications and that you downloaded the build matching your chip.

Windows: SmartScreen “Windows protected your PC”

  1. In the dialog choose More info.
  2. Choose Run anyway. SnapByFace is made by a solo developer and does not yet have a verified publisher certificate — that is why SmartScreen flags it. Verify the SHA-256 checksum on the download page to confirm the file is genuine.
  3. If your organization blocks it, ask IT to allow the publisher.

Performance: indexing is slow

Work through these in order:

  1. Check the video sampling interval. 1 second is the default; 2–5 seconds is a sensible first pass over hours of footage.
  2. Change the threshold instead of re-indexing. It re-matches existing embeddings and never re-analyzes media.
  3. Move media to a local SSD. Network shares and USB hard drives are usually the real bottleneck.
  4. Let it run in the background and pause/continue as needed; progress is kept.
  5. Avoid copying or editing media while indexing — changed files get re-queued.
  6. Close other heavy apps so SnapByFace keeps the CPU.

An unfinished task after a crash or restart

On startup, SnapByFace asks whether to continue the unfinished task. Accepting resumes from the last saved progress; declining leaves already-indexed files in place.

If the same file fails every time, take its path from the log and try opening it in another player — a corrupt file or an unusual codec will fail repeatedly, and excluding that folder is faster than retrying.

Results look wrong

  • Too many wrong faces: raise the threshold. See Threshold Tuning.
  • Too many misses: lower the threshold, then check whether the faces are actually detectable (size, lighting, blur).
  • A person never matches: replace their reference photo with a frontal, single-face, evenly lit shot.
  • Video hits have fuzzy boundaries: expected — ranges are built from sampled frames and are accurate to about one sampling interval.

Resetting the app state

As a last resort, close SnapByFace and remove its working folder:

# macOS
rm -rf ~/.snapbyface

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.snapbyface"

:::caution This deletes the index, your settings, and your activation state. Your original photos and videos are untouched. Afterwards you must re-add media folders, re-run the analysis, and re-enter your license code. :::

Next steps