Skip to main contentGBOSSTABTime and Billing

Desktop troubleshooting

Desktop appLogin won't stick, app icon flickers, 'user not provisioned' errors.

Desktop troubleshooting

The handful of issues we've actually seen on the desktop, and how to clear each one. If none of these matches what you're seeing, send the symptoms to your firm admin or to GBOSS support.

"Loading…" forever, or "Couldn't load sessions" on the web

This is the localhost-cookie-collision trap, handled in frontend/src/frontend/lib/api.ts. It only happens during local development when you have two GBOSS apps (TAB + CRM, say) open in the same browser on the same machine, they share the same cookie domain (localhost) and end up overwriting each other's session.

The web app's API wrapper detects 403 responses with "not provisioned" in the body, clears the stale platform_session cookie at the document level, and bounces back to /login?reason=wrong-app. So in most cases it auto-recovers. If it doesn't:

  1. Open DevTools (right-click anywhere → Inspect).
  2. Go to the Application tab (Chrome/Edge) or Storage tab (Firefox).
  3. Find Cookies → http://localhost.
  4. Delete the platform_session cookie.
  5. Reload and sign in fresh.

This is purely a local-dev annoyance. In production each app lives on its own subdomain so cookies are isolated. Reference: docs/local-dev.md §10.

Desktop says "Sync failed" in the status strip

The status strip at the top of the desktop window is your first stop. When sync fails the strip shows "✗ Sync failed, <reason>", and the on-screen alert below shows the same reason.

Most common causes:

  • Backend URL is wrong. Open Settings (gear icon) and check the Backend URL field. It should match your firm's TAB URL exactly, e.g. https://tab.<your-firm>.gbossone.com. In dev / generic builds the default is http://localhost:9080.
  • Liberty backend is offline. Refresh with the ↻ button after confirming the server is up.
  • Cookie / token expired. A 401 from any request triggers onUnauth(), which kicks you back to the login view.

App icon does nothing useful, buttons unresponsive

After a build update the webview state can wedge. The fix:

  1. Right-click the tray icon (Mac menubar) and pick Quit GBOSS TAB. Closing the window with the red dot leaves the process running.
  2. Confirm in Activity Monitor (Mac) that no GBOSS TAB process is alive.
  3. Relaunch from Applications.

If it's still broken, fully reinstall:

  1. Quit the app.
  2. Drag GBOSS TAB from Applications to the Trash.
  3. Download the latest installer from the downloads page and reinstall.

"User not provisioned in TAB"

Your account exists in another GBOSS app (the platform knows who you are) but app_users doesn't have an active row for you in this firm. The web wrapper handles this in api.ts by clearing the cookie and routing to /login?reason=wrong-app; on the desktop it shows as an API error in the alert strip.

Fix: ask your firm admin to open Admin → Users in the web app and confirm you're listed and Active. Once you've been added (today this is provisioned externally, see Users and roles), sign out of the desktop and back in.

The desktop says it's connected but the web doesn't see my timer

Today the desktop hits the API directly, there's no offline buffer in use, so a started timer on the desktop should appear on the web on its next page reload (the web's RunningTimerContext polls every 30 seconds, and the dashboard banner reads from it).

If it really isn't showing:

  1. Open desktop Settings (gear icon) and check the Backend URL.
  2. Copy the URL into your browser and confirm it's the same backend the web is talking to.

It's not unusual for someone to be looking at staging in the browser while the desktop is pointed at production (or vice versa). If the URLs differ, update one of them.

"App is damaged" or "from an unidentified developer" on Mac

The Mac build is currently unsigned (signingIdentity: null in tauri.conf.json), so Gatekeeper blocks the very first launch. See Installing the Mac desktop app for the one-time right-click → Open workaround. Signed builds are on the roadmap.

Last resort: reset the desktop

If something is stuck and nothing else helps, wipe the desktop's local state and start fresh. This won't lose any of your time entries, those live on the server.

  1. Quit GBOSS TAB fully (tray icon → Quit).
  2. In Finder, press Cmd + Shift + G and paste ~/Library/Application Support/gboss-tab.
  3. Move that folder to the Trash. It contains session_token, backend_url, and the unused tab-buffer.sqlite.
  4. Relaunch GBOSS TAB and sign in from scratch.

Related