# Troubleshooting

Foxora is built to recover on its own — the engine runs as a supervised process the app restarts if it dies, and the runtime link self-repairs. When something still won't budge, these are the fixes, in the order worth trying them.

> Start with the connection probesMost issues are a connection that didn’t come up. Open Settings (⌘, / Ctrl+,) → Advanced — it shows a live status dot for the Engine, Login, and Gateway. On the CLI, foxora doctor checks the same things. Whatever reads Unreachable is your starting point. See the Settings reference.

## The app is stuck on “Starting Foxora”

On launch the app spawns the engine daemon and polls it until /health answers on 127.0.0.1:4097. If it sits on “Starting Foxora”, the engine either hasn’t come up or a previous instance is still holding the port.

### What to try

- Give it a moment. First launch (and the first launch after an update) provisions the runtime, which can take a minute on a slow connection.
- Quit fully and reopen. Make sure the app is completely closed first — an orphaned engine can keep the port busy and stall the new one.
- Check the port. A stray process on :4097 shadows a fresh engine. Find and stop it, then relaunch:

```
# who's on the engine port?
lsof -i :4097
# stop it by PID, then reopen Foxora
kill <pid>
```

> The engine is supervisedYou don’t normally manage the engine yourself — the app owns its lifecycle and restarts it automatically if it exits. If it never reaches ready at all, the issue is usually the runtime (next section) rather than the engine process.

## Engine unreachable

If chat shows “couldn’t reach the engine” or Settings → Advanced marks the Engine row Unreachable, requests aren’t getting through to :4097.

### What to try

- Re-check after a few seconds. The probe re-runs; a transient restart clears on its own.
- Confirm your network. The Gateway row needs an internet connection — a blocked or offline network shows it Unreachable even when the local engine is fine.
- Make sure you’re signed in. A signed-out app can’t reach the gateway. Sign in again from Settings → Account (or foxora login).
- From the CLI, run the one-shot diagnostic:

```
foxora doctor
# checks: platform · runtime · engine · account · gateway
```

## Stale or broken runtime

The engine and its bundled bun live in ~/.foxora/runtime/current. The app expects to find engine.js and bun there. If that link is missing or points at a half-installed version, the engine won’t start — foxora doctor reports the runtime as not installed.

Foxora self-heals where it can: when current is missing it relinks to the newest good versioned runtime it finds. When it can’t, re-provision:

```
# re-provision the runtime (engine · memory · workspace · bun)
foxora setup

# update the CLI and refresh the runtime to the latest
foxora update
```

> Force a clean reinstallIf a runtime is genuinely corrupt, you can force a fresh provision by setting FOXORA_SETUP_FORCE before foxora setup. This replaces ~/.foxora/runtime/current — your sessions and memory live elsewhere in the data folder and are untouched.macOS / LinuxWindowsFOXORA_SETUP_FORCE=1 foxora setupCopy

## Where logs & the data folder live

Everything Foxora keeps on this device — the runtime, Memory Den, sessions, and workspace files — lives in one predictable data home:

```
~/.foxora
```

It’s a hidden dot-folder by convention (like ~/.docker). The fastest way to open it is Settings → Advanced → Foxora data folder → Reveal, which opens it in Finder / Explorer.

### Crash log

If the app shell itself faults, it writes a crash log to your system temp directory so the fault is never silent:

```
# in your temp dir, e.g.
$TMPDIR/foxora-crash.log
/tmp/foxora-crash.log
```

> Sharing diagnosticsWhen reporting an issue, the output of foxora doctor plus the data folder path tells us almost everything we need — platform, runtime version, engine state, and whether the gateway is reachable.

## Resetting local preferences

If the UI looks wrong — a broken theme, accent, or font — you can reset just the on-device preferences without touching your account or sessions. Open Settings → Advanced → Reset local preferences, then confirm. It clears theme, scheme, accent, and font and reloads.

> What reset does and doesn't touchResetting preferences only clears appearance settings stored on this device. Your account and sessions are untouched. It does not reinstall the runtime — for that, use foxora setup (above).

## Still stuck?

Work through it in this order, and you’ll have caught the vast majority of problems:

- Check Settings → Advanced probes (or foxora doctor).
- Quit fully and reopen; free up :4097 if it’s held.
- Re-provision the runtime with foxora setup.
- Reveal the data folder and grab the crash log if the app faulted.
- Reset local preferences if only the UI looks wrong.

Need a fresh install instead? See Installing Foxora, or the Settings reference for every toggle in one place.