Troubleshooting | Snipstack Docs

The global hotkey does not work

When Snipstack starts and cannot register the hotkey, it tells you:

“Couldn’t register … - another app is using it.” Click Choose another, or change it under Settings > General. If the new combination is taken too, Snipstack keeps your previous one.
“Global shortcuts aren’t available in this session.” Your desktop does not let apps register global shortcuts (common on Wayland). Bind the command snipstack --quick to a key in your desktop’s keyboard settings instead; it opens quick search the same way.
“Couldn’t register ….” The combination cannot be used. Choose another.

While the hotkey is not registered, the tray menu item reads Quick search (hotkey unavailable); clicking it opens the hotkey setting. You can always open quick search from the tray, the palette or snipstack --quick.

On a Wayland session Snipstack uses the desktop’s global-shortcuts portal when there is one. On X11, a combination that fails is reported as taken by another app.

No tray icon on Linux

Stock GNOME shows no tray icons without the AppIndicator extension (Ubuntu and Pop!_OS include it). Without a tray, Snipstack started at login opens its window instead of hiding. If the window is hidden and you cannot see the icon, launch Snipstack again: the running copy shows its window. If the tray icon cannot be created at all, closing the window quits Snipstack.

Windows or macOS warns about the app

The builds are not code-signed yet. Follow the first-launch steps: More info > Run anyway on Windows; System Settings > Privacy & Security > Open Anyway on macOS, or the xattr command if macOS says the app “is damaged”.

Auto-paste does not paste

The text is always copied first, so you can paste it yourself. If the paste fails, a notification says “Copied. Paste failed.”

macOS: Snipstack needs Accessibility access to send Cmd+V. Use Open Accessibility settings in the setting and allow Snipstack.
Linux: install xdotool (X11) or wtype (Wayland). Without one, the setting is disabled.
Windows: nothing extra is needed.

See Auto-paste.

Sync

Click the sync badge to see the error. Copy details puts the error code and message on the clipboard.

Code	Message	Fix
`AUTH`	The database rejected the token.	Create a new token (`turso db tokens create <name>`) and Reconnect.
`NETWORK`	Could not reach the database. Check your connection and the URL.	Check your network and the URL. Background sync shows Offline and retries by itself.
`SCHEMA_TOO_NEW`	This database was set up by a newer Snipstack. Update Snipstack to sync with it.	Update Snipstack on this device. Sync waits until you press Sync now.
`INVALID_URL`	That database URL is not valid.	Reconnect with a `libsql://`, `https://` or `wss://` URL, without `?` or `#` parts.
`REMOTE`	The database reported an error.	Read the server’s message in the details box. Check your database in Turso.
`UNKNOWN`	Something went wrong while syncing.	Retry. If it keeps failing, check the log.

Other messages:

“Snipstack could not read the saved database token on this device. Reconnect to resume syncing.” The encrypted token could not be read. Reconnect with the URL and a token.
“This system has no secure storage for the database token, so sync cannot be set up. Snipstack keeps working locally.” Snipstack only stores tokens in the system’s secure storage.
“The sync process stopped unexpectedly.” Retry; if it repeats, check the log.

Your local changes are safe in every case: they stay on the device until a sync succeeds.

Other errors

Message	Meaning
That item no longer exists. It may have been deleted on another device.	The item is gone, for example deleted on another device.
That change conflicts with the current state. Refresh and try again.	Something changed in the meantime. Try again.
Something went wrong. Your data is safe; try again.	An unexpected error. Try again; check the log if it repeats.

Logs and bug reports

Open the logs from Settings > About > Open logs folder. They are logs/main.log in the data folder on Windows and Linux, and ~/Library/Logs/Snipstack/main.log on macOS.
Turn on Settings > About > Detailed error logging to add stack traces while you reproduce a problem.
Copy diagnostics (About, or the palette) puts a report on your clipboard: versions, settings, sync health, counts and the last 200 log lines, with credentials, the updater’s install ID, database addresses and folder paths removed and no snippet content. Nothing is sent; paste it where you choose.