Skip to content
Fexl Lite

Connection issues

The desktop app ships with a Go server bundled as a Tauri sidecar. On launch, Tauri starts that binary on localhost:8089 and the React UI connects to it. When the connection never lands, the app shows a “Server is starting…” splash that doesn’t go away. This page covers what’s actually happening underneath and how to clear it.

Updated 4 May 2026·For v2.2.0·4 min read
splash · 'Server is starting…' · stuck

Find the log first

Every diagnosis on this page starts with the server stderr log. Open it in any text editor:

  • macOS — ~/Library/Application Support/com.minib2c.pos/server-stderr.log
  • Windows — %APPDATA%\com.minib2c.pos\server-stderr.log
  • Linux — ~/.local/share/com.minib2c.pos/server-stderr.log

A healthy boot ends with listening on :8089. If you see anything else as the last line — bind: address already in use, a permissions error, no log file at all — that’s your symptom.

”Server is starting…” splash never clears

Symptom 1 — log ends with bind: address already in use

Cause — port 8089 is occupied by another process. Most often a previous Fexl Lite that didn’t shut down cleanly, but occasionally an unrelated dev server.

1

Find what's holding the port

  • macOS / Linux — lsof -i :8089
  • Windows (PowerShell) — Get-NetTCPConnection -LocalPort 8089

The output shows the PID and the process name.

2

Kill the stale process

  • macOS / Linux — kill -9 <PID>
  • Windows (PowerShell) — Stop-Process -Id <PID> -Force

If it’s another Fexl Lite, fully quit any running tray icons before relaunching.

3

Relaunch Fexl Lite

The splash should clear within 2–3 seconds. If bind errors return, reboot — something is holding the port across restarts.

Symptom 2 — log is missing or zero bytes

Cause — the sidecar binary never started. Usually antivirus quarantined it, or filesystem permissions on the install dir are broken.

  • Windows — open Windows Security → Virus & threat protection → Protection history. If you see retail-server.exe quarantined, restore it and add an exclusion for %LOCALAPPDATA%\Fexl Lite\. Defender and several third-party AVs flag the Go binary on first run because it’s an unsigned PE that opens a network port.
  • macOS — Gatekeeper occasionally blocks the sidecar on first run. Open System Settings → Privacy & Security and look for “retail-server was blocked” near the bottom. Click Allow Anyway and relaunch.
  • Linux — confirm the sidecar is executable: ls -l <install-dir>/retail-server. If the x bit is missing, chmod +x it.

Symptom 3 — log shows listening on :8089 but the splash still hangs

Cause — the server is up, but the Tauri webview can’t reach it. Almost always a local firewall blocking loopback connections, or a hosts-file override pointing localhost somewhere unexpected.

1

Confirm the server actually answers

In a terminal, run curl http://localhost:8089/api/health. A healthy server replies with a small JSON {"status":"ok"}. If curl also hangs, the firewall is the culprit.

2

Allow the desktop app through the firewall

  • macOS — System Settings → Network → Firewall → add Fexl Lite to the allowed apps list.
  • Windows — Settings → Network → Windows Firewall → Allow an app → tick both Private and Public networks for Fexl Lite.
  • Linux — depends on the distro. UFW: sudo ufw allow from 127.0.0.1 to any port 8089.
3

Check /etc/hosts

localhost must resolve to 127.0.0.1. A custom hosts-file override (sometimes installed by VPN clients) can break loopback. Open the hosts file and confirm the line 127.0.0.1 localhost exists and isn’t commented out.

Cloud-mode failover

When cloud sync is enabled, the API client hits the cloud server first and falls back to the local Go server only on network failure. If your internet drops mid-shift you’ll see a “Working offline” badge in the header — sales keep ringing, the local server takes over, and the sync worker queues the changes. When connectivity returns, the queue drains automatically.

”Server is starting” splash on every launch (slow boot)

Some machines take 5–10 seconds to bring the sidecar up — fine on first install, annoying every launch. The usual cause is a slow disk on the SQLite path, or an antivirus scanning the binary on every start.

  • Move the data dir off a network share. The default is local, but some IT setups redirect %APPDATA%. The DB path is ~/Library/Application Support/com.minib2c.pos/retail.db (macOS) or %APPDATA%\com.minib2c.pos\retail.db (Windows). If that’s on a network share, performance is unusable.
  • Add an AV exclusion for the Fexl Lite install directory so the sidecar isn’t re-scanned every launch.

Still stuck?

  • Try the in-app Diagnostics view: Settings → System → Diagnostics. It runs a health check against the local server and the cloud (if enabled) and reports the failure mode.
  • If you can open the app but nothing loads, jump to Sync issues — the connection might be fine, but the data isn’t.
  • Open a support ticket with: (a) OS + version, (b) the last 50 lines of server-stderr.log, (c) whether cloud sync is enabled, (d) the exact splash message you’re seeing.