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.

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.

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.

• 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.