# Troubleshooting

Something's not working? Find your symptom below — each entry says what's probably going on and how to fix it. If nothing here helps, the [bottom of this page](#still-stuck) tells you where to ask.

## SearchBox won't open at all (Windows 10)

**Likely cause:** Windows 10 doesn't always include Microsoft's WebView2 component, which SearchBox uses to draw its window.

**Fix:** Install the free [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) from Microsoft (choose the "Evergreen" installer), then start SearchBox again. Windows 11 already ships with it.

## "Windows protected your PC" when installing

**What's going on:** Windows SmartScreen is cautious about installers from small publishers it hasn't seen many times.

**Fix:** Click **More info**, then **Run anyway**. Your download is fine — you can verify it, if you like, against the `.sha256` checksum file published next to each installer on the [releases page](https://github.com/SourceBox-LLC/SearchBox/releases).

## Search returns nothing, or "search engine not running"

**Likely cause:** the search engine (a companion program called Meilisearch that SearchBox runs alongside itself) isn't running.

**Fix:**

1. Open **Settings → Search Engine**.
2. Check the status — if it's stopped, start it, and make sure **Auto-start** is on.
3. Installed versions include the engine automatically. If the status complains about a missing program (`meilisearch_path not configured`), the **Binary Path** setting needs to point at the Meilisearch program — on a normal install you should never see this; it can happen on hand-rolled setups.

Also worth checking: did indexing actually finish? The bell icon shows a notification when a folder completes.

## A file I added recently doesn't show up

**Likely cause:** SearchBox indexed the folder before the file existed and hasn't re-synced.

**Fix:** Click the upload icon → **Index Folder** tab → **Sync Folders** (or use **Settings → Indexed Folders**). Syncing picks up new, changed, and deleted files.

## The vault asks for my password after every restart

**Not a bug — a feature.** The vault's key lives only in memory and is wiped when SearchBox closes, so a stolen or copied hard drive can't expose your files. Unlock it in **Settings → Vault Security** when prompted. Full story in [The private vault](./vault.md#locked-after-a-restart--thats-on-purpose).

## I forgot my password

**Fix:** On the login screen, click **Forgot password?** and paste your **recovery key** (the long code you saved during setup), then choose a new password.

> ⚠️ Without the recovery key there is no way to reset your password — nothing about your account exists outside your PC, which means there's no company that can let you back in. If you can still log in right now, go make a fresh key: **Settings → Account → Generate Recovery Key**.

## The update check found a new version, but there's no install button (Linux)

**What's going on:** the one-click in-app update installs a Windows installer, so it's Windows-only.

**Fix:** on Linux, download the newest tarball from the [releases page](https://github.com/SourceBox-LLC/SearchBox/releases) and extract it over your old one — your data lives elsewhere (`~/.local/share/searchbox`) and is untouched. Details in [Linux and Docker](./linux-and-docker.md).

## SearchBox opens and immediately closes (or nothing happens)

**Likely cause:** SearchBox is already running. Only one copy can run at a time — a second one notices and quietly exits.

**Fix:** check your taskbar/system for the existing window. If you genuinely can't find one, another program may be using port 8080; close it or set a different port with the `SEARCHBOX_PORT` environment variable.

## Docker: the app runs but every search fails

**Likely cause:** the app and the Meilisearch container aren't using the same key. In Docker, both sides read the `MEILI_MASTER_KEY` environment variable — this was fixed in v0.3.18, so first make sure your image is current.

**Fix:** update to the latest image, set a strong `MEILI_MASTER_KEY` in your compose file (not the sample value), and restart the stack: `docker compose down && docker compose up -d`.

## Where are the log files?

When something odd happens, the logs usually say why:

- **Windows (installed):** `%LocalAppData%\SearchBox\log\` — paste that into the File Explorer address bar.
- **Linux (tarball):** `~/.local/share/searchbox/log/`
- **Docker:** `docker logs searchbox`

A new file is started each day; the newest one is the one you want.

## Still stuck?

- Search or ask in [Discussions](https://github.com/SourceBox-LLC/SearchBox/discussions) — questions welcome, no such thing as too basic.
- Found a genuine bug? [Open an issue](https://github.com/SourceBox-LLC/SearchBox/issues) and include what you did, what happened, and a snippet from the newest log file if you can.

---
[← Back to the manual](./README.md)