Troubleshooting

Short playbooks for the problems you are most likely to hit. Each is symptom → likely cause → what to do.

The app or dev server won’t start

Likely cause: a toolchain or port mismatch.

Confirm Node.js 24+, pnpm 11+, and the stable Rust toolchain are installed.
Run make bootstrap once, then make dev.
The web UI needs port 5173 and the local API needs 8787. If another process holds one, stop it (or set VOYALIER_DATA_DIR and adjust the port) and retry.
Run make check to surface build, lint, and type errors.

Voyalier won’t open on first launch

Likely cause: the installers aren’t code-signed yet, so your OS warns you once.

macOS, “unidentified developer”: double-click Voyalier and let macOS block it, then go to System Settings → Privacy & Security, scroll to the message about Voyalier, and click Open Anyway. (Right-click → Open also works on macOS 14 and earlier; Apple removed it in macOS 15.)
Windows, “Windows protected your PC”: click More info, then Run anyway.
Either way, the decision sticks — later launches are normal. See Download and install for what the warning does and doesn’t mean.

AI assist fails

Likely cause: no key, no local model, or a provider-side error.

“No key” / refused before sending: open AI providers and add an OpenAI or Anthropic key (stored in your OS keychain), or pick the on-device provider.
On-device (Ollama) not found: install Ollama, pull a model (ollama pull llama3.2), and make sure it is running on localhost:11434.
Cloud request fails: Voyalier surfaces the provider’s real error (an invalid key, an exhausted quota, or a rate limit). Fix the underlying cause with your provider and try again — the request is exactly what you saw in the preview, so nothing unexpected was sent.

“Ask about this trip” says no local model was found

Likely cause: chat is on-device only, and there is no Ollama model for it to use.

Chat never falls back to a cloud provider, so an OpenAI or Anthropic key will not fix this and is not meant to — see why chat is local-only.
Open AI providers → On-device AI and follow the setup: install Ollama, start it, and pull a model. The panel points you there instead of showing an input box, because an input box would have nothing to answer with.
If Ollama is installed, confirm it is actually running on localhost:11434, then reopen the panel.

Fetching a resource’s page details does nothing, or the button is missing

Likely cause: the setting that allows it is off, which is the default.

Voyalier never fetches a page you saved until you turn on allow fetching page details. While it is off there is no button to press — that is the setting working, not a broken control.
Saving a resource contacts nothing by design, so a saved link with no stored text is a normal state, not a failed fetch.
With the setting on, a fetch still needs a reachable page and a network connection. Very long pages are stored truncated and say so.
Turning the setting back off takes one click. See Research resources.

The map is blank

Likely cause: no consent click, no WebGL, or no network.

The map only loads after you click Show map — the click is the consent.
The basemap needs WebGL and a network connection to fetch tiles from OpenFreeMap. In an environment without WebGL (some headless setups) the frame stays empty by design rather than crashing.

Official advice or weather won’t fetch

Likely cause: these are consented, network-only, and scoped.

Both fetch only on an explicit click. Check your connection and retry.
FCDO travel advice covers UK-passport holders and uses a curated country list; a destination outside that list won’t have a snapshot. The linked official sources are always available regardless.

Likely cause: the interface cannot reach Voyalier’s local engine.

The topbar, global recovery message, and failed work area should all agree on Offline. Reconnect the browser development service or let the desktop app finish reopening, then choose Retry.
A successful retry returns the topbar to Ready and reloads the affected local view. Validation or storage errors stay attached to their own action and do not masquerade as an outage.
When running from source, confirm the Axum API still answers on 127.0.0.1:8787; make dev starts both it and the web UI.

A city pack won’t download

Likely cause: the pack contents haven’t been published yet.

Pack contents are served from the project’s packs-v1 release, which is populated by a maintainer-run build workflow. Until a pack is published, a download fails gracefully (nothing is stored). The catalog and per-layer licenses still list what each pack will contain.

I’m locked out of my vault

If you remember your passphrase: enter it on the unlock screen when the app starts.

If you have forgotten it: there is no recovery. Your passphrase is only ever used locally to derive a key and is never stored, so no one — including you — can decrypt the data without it. Your options are to keep trying to remember it, or to start over with an empty workspace by removing the database (see below), which permanently discards the encrypted trips.

An update won’t install, or the app won’t open after one

Likely cause: a transient GitHub/network issue, or a rare bundle-swap problem.

“Couldn’t check for updates”: Voyalier keeps update errors deliberately coarse (it never guesses at GitHub’s internals). Check your connection and click Try again, or open the releases page to download a build by hand. If you’re offline it says so instead.
The update downloaded but the app won’t reopen (macOS): re-download the latest build from the releases page and reinstall it into Applications. Your data is safe — trips, documents, and your keys live outside the app bundle, so a reinstall keeps everything, and Voyalier took a database backup right before the update (see below).
On macOS the app must be updated from /Applications — updating a copy run from Downloads or a mounted disk image can fail to swap in place.
Windows updates by closing, installing, and reopening on their own (under a minute); there is no separate “restart” step.

Where your data lives (and how to back up or reset)

Everything is stored locally in a single SQLite file, voyalier.sqlite3:

macOS: ~/Library/Application Support/com.voyalier.Voyalier/
Windows: %APPDATA%\voyalier\Voyalier\data\
Linux: ~/.local/share/voyalier/

Set VOYALIER_DATA_DIR to point Voyalier at a different location. Voyalier resolves the path, so two spellings of one directory are one workspace.

Each data directory keeps its own vault key from 0.10.2 on, so a second workspace can set a passphrase or restore a backup without affecting the first. Before 0.10.2 they shared one key, and either action would have left the other workspace’s encrypted fields unreadable. If you ran two workspaces on an earlier version and one of them stopped opening its saved trips, that is why.

Back up: copy that voyalier.sqlite3 file somewhere safe while the app is closed. Sensitive fields inside it are already encrypted at rest.
Reset: delete the file to start with an empty workspace. This is irreversible.
Pre-update backups: Voyalier keeps its most recent database backups in a backups/ subfolder of that same directory (named pre-update-*.sqlite3). Each is a complete snapshot, so a trip you delete still exists in older backups until they rotate out — delete the files if you want them gone. Backups are never included in an exported or shared brief.

Your provider API keys and the vault key live separately in the OS keychain (service com.voyalier.keys), not in that file. Removing a provider key is done from the AI providers panel.

Clearing up after workspaces you no longer use

Each data directory keeps its own keys, and deleting the directory does not remove them — the keychain has no idea the database is gone. If you have tried a few VOYALIER_DATA_DIR locations, run:

voyalier-server vault-prune            # lists what it would remove
voyalier-server vault-prune --apply    # removes it

It only removes accounts whose database no longer exists, and never the default installation’s. It also cannot see workspaces you last opened before 0.10.4 — the keychain cannot be listed, so Voyalier only knows about the ones it has recorded since. Anything older has to be removed by hand in Keychain Access, under the service com.voyalier.keys.