Skip to content

Troubleshooting

Jump to bottom
Rynn edited this page Apr 24, 2026 · 1 revision

Troubleshooting

English · 简体中文

Symptom → root cause → one-line fix.

CLI

"unsupported engine" / Node version error

Node < 20 isn't supported. Check:

node --version

Upgrade via nvm, fnm, brew upgrade node, or apt install nodejs.

Port 7680 already in use

The dashboard server auto-fallbacks to 7681, 7682, etc — the actual port is printed at startup. Force one manually if you need a stable URL:

PORT=7700 tokentracker serve

Find the offender:

lsof -i :7680

A provider isn't being detected

tokentracker status       # See per-tool state
tokentracker doctor       # Deeper health check
tokentracker activate-if-needed  # Re-run detection

If the provider still shows skipped and you know it's installed, attach tokentracker diagnostics output to a new issue.

Queue shows pending but nothing uploads

Happens when cloud sync is enabled but the device token expired or the backoff timer hasn't elapsed.

  • Force a sync: tokentracker sync
  • If you don't use the cloud leaderboard at all: the queue is harmless, it just accumulates locally — feel free to ignore
  • Reset upload backoff / queue: tokentracker doctor will suggest the right command based on current state

"copy registry" test failure after editing translations

The validator expects every key in dashboard/src/content/copy.csv to be referenced in source. Run:

npm run validate:copy

It prints the exact keys that are orphaned or missing.

Uninstall everything

tokentracker uninstall

Removes every hook across all detected tools, plus ~/.tokentracker/. Safe to re-run.

macOS App

"TokenTrackerBar can't be opened" — unidentified developer

TokenTrackerBar uses ad-hoc signing (no paid Apple Developer ID → no notarization). Gatekeeper blocks first launch.

  1. System Settings → Privacy & Security
  2. Scroll to Security — you'll see "TokenTrackerBar was blocked to protect your Mac"
  3. Click Open Anyway
  4. Confirm in the follow-up dialog

One-time. Old-macOS alternative: Finder right-click → Open → Open in the confirmation.

"TokenTrackerBar is damaged and can't be opened"

Gatekeeper reacting to com.apple.quarantine attached to every downloaded file — not an actual problem. Clear it once:

xattr -cr /Applications/TokenTrackerBar.app

"TokenTrackerBar wants to access data from other apps"

Required for Cursor and Kiro integrations. They store auth tokens / usage data in their own ~/Library/Application Support/ folders, which macOS protects with the App Management permission.

  • ✅ Allow if you use Cursor or Kiro
  • ❌ Don't Allow — those providers get silently skipped, everything else works

Ad-hoc signed builds re-prompt after each upgrade because the signing identity changes per build.

Menu bar app won't start / no status icon

Usually the embedded Node server couldn't bind a port. Check the log:

tail -f ~/Library/Logs/TokenTrackerBar/server.log

Common causes:

  • Another TokenTrackerBar instance is already running → Quit via menu or pkill -f TokenTrackerBar
  • Corporate firewall blocks loopback → try PORT=7700 env var launched via Terminal
  • Embedded Node binary got quarantined separately → xattr -cr /Applications/TokenTrackerBar.app/Contents/Resources/EmbeddedServer/

Desktop widgets show "No data"

Widgets read from an App Group snapshot written by the main app. If the main app isn't running or hasn't synced yet:

  1. Launch TokenTrackerBar from the menu bar
  2. Wait ~5s for the initial sync
  3. Right-click the widget → Edit Widget → force a reload

If widgets still show empty after the main app has valid data, the App Group link might be broken — reinstall the app (DMG or brew reinstall --cask).

Dashboard / Web

Dashboard shows 0 tokens even though I use AI tools

Likely the hooks aren't wired. Run:

tokentracker status

If every tool says configured but data is still 0: your tools haven't been used since the hook was installed. Use them once and re-check — the hook only fires on session end, not retroactively.

Language switch doesn't update everything

Fixed in 0.5.84+ — if you see stale text, force-refresh (Cmd+Shift+R) once. If it still repros, open an issue with the page URL and the locale you're switching between.

Login / leaderboard is stuck

Cloud sync uses InsForge. Check:

  • Are you online?
  • Did the OAuth callback complete? The browser should have redirected back automatically
  • As a last resort: sign out and back in via the dashboard header

Local usage works offline regardless of auth state — cloud is purely for the leaderboard and cross-device sync.

Still stuck?

  • Paste tokentracker diagnostics output into a new issue — it's sanitized (no prompt content, no tokens/secrets)
  • Ask in Discussions for anything open-ended

English

简体中文

Clone this wiki locally