Everything we know about fixing TabMind / XKG when something goes sideways. Scan the table of contents; each section is one symptom + the fastest known fix.
Last revised: 2026-08-21
On macOS you'll see "App is damaged and can't be opened" on the first install because the binary isn't yet notarized for your machine. Right-click the file in Finder, choose Open, then click Open in the dialog. The OS will remember the exception. This is fixed for all post-v1.0.0 builds.
The TabMind extension is unpacked during the beta. Open
chrome://extensions, enable Developer mode, then
Load unpacked and select the
tabmind-extension/ directory inside your install path. On Brave /
Edge / Arc the same toggle exists at brave://extensions,
edge://extensions, etc.
On older Ubuntu LTS (20.04 and earlier) the system libsqlite3 is too
old. We bundle SQLite 3.45 with the AppImage / .deb / .dmg so this should
not happen — if it does, please open an issue with the output of
ldd $(which xkg-desktop).
Check the three pre-conditions, in order:
If the icon is grey, click it once and re-grant the
tabs + tabGroups permissions.
Almost always: the FTS5 index is stale. Open Settings → Index → Rebuild now. Rebuild time is ~2 seconds per 1,000 messages; you can keep using the app while it runs.
Grok (Free) requires a key from console.grok.x.ai. The keys from
x.ai or the consumer app are different credentials and will return
401 invalid_api_key — regenerate at the developer console and paste
the new one into Settings → Providers.
We're rate-limited at the upstream LLM provider, not at our tier. The client will retry with exponential backoff up to 4 times (so 1s, 2s, 4s, 8s). If you burst more than ~60 requests/minute you'll start seeing 429s in the logs; either back off or upgrade to a higher upstream tier.
That is a bug; please email security@seele.agency with the log
snippet immediately. As of v1.0.0 keys are scrubbed from the JSON-log
serializer at the source — if you see one, something is bypassing the
scrubber and we want to know.
Run the built-in diagnostic:
xkg-cli sync-diag --device-a=$(hostname) --device-b=<peer>Most common root causes:
server_url in ~/.config/xkg-desktop/settings.json.chronyc tracking (Linux) or
sudo sntp -sS time.apple.com (macOS).You have the right hub, the right device, the wrong key. The hub is
handing back an envelope encrypted for a different device_id; either
your device_id mismatches what you think, or another device of yours
is on the same hub with a different key. Delete
~/.local/share/xkg-desktop/keys.json on the confused device and
re-register.
You're almost certainly seeing the §1Sync
property 6 ("replaying an old envelope is idempotent") exercise itself
under load. The test
tests/deferred/e2e_three_devices.rs::three_devices_converge_after_exchange
asserts this and passes; in production it can take 20–60 seconds for
larger stores. If the spin locks longer than 2 minutes, please file an
issue with the output of xkg-cli sync-diag --verbose.
FTS5 keeps a contentless shadow table plus the main one; both grow linearly with message count. Normal range is 30–80 KB per 1,000 messages. If you're seeing > 5 MB per 1,000 messages, your store has un-pruned product-link rows — open Settings → Storage → Vacuum.
v1.0.0 ships migration v7 which renames the legacy tasks table to
preserve user data. If your database is from a pre-v0.7 build the rename
can fail because of leftover indexes. Run:
sqlite3 ~/.local/share/xkg-desktop/store.db \
"DROP INDEX IF EXISTS idx_tasks_legacy;
DROP TABLE IF EXISTS tasks_legacy;"then relaunch — the migration will retry and succeed.
Open an issue at github.com/griptoad26/xkg-server/issues with:
xkg-cli diag --all (PII is auto-redacted).~/.local/share/xkg-desktop/xkg-desktop.log
(or the platform-equivalent path on macOS / Windows).For security issues, do not open a public issue — follow /acknowledgments.html for our coordinated disclosure process.