Troubleshooting

This page collects the problems people run into and the fix for each, with a short note on why it happens. Many of them are not bugs but limits of the platform, so the platform each one applies to is in its heading.

If nothing here matches what you see, read the FAQ or open an issue on GitHub.

Global shortcuts do nothing (Linux)

Symptom. Ctrl+Alt+Shift+A and the other hotkeys do nothing, or Snipdeck shows “Failed to register hotkeys”.

Why it happens. On Wayland, global shortcuts go through the desktop portal. The portal refuses a program that has no application id, and a program installed outside a sandbox gets one only when the desktop starts it from its .desktop entry. Started from a terminal, Snipdeck has none, and every shortcut fails to bind.

What to do:

• Install Snipdeck with install.sh (or, from source, packaging/linux/install-from-source.sh) and start it from your applications menu, not from a terminal.
• The first time the shortcuts bind, your desktop shows a dialog to approve them. Approve it once.
• After that, the desktop owns the shortcuts: change them in your desktop’s keyboard settings. The hotkey_* keys in settings.json are only what Snipdeck proposes the first time.

Super+Alt+drag does nothing, or snips open in the wrong place (GNOME)

Symptom. On GNOME, holding Super+Alt and dragging moves a window or does nothing. Or snips open wherever GNOME puts them instead of where you captured them, and they do not stay on top.

Why it happens. Both are the job of Snipdeck’s GNOME Shell extension, [email protected]. Wayland does not let a program place its own windows, keep them on top, or watch the mouse globally; code inside GNOME Shell can. If the extension is not loaded, GNOME treats Snipdeck like any other program.

What to do:

1. Make sure Snipdeck is running. The extension takes over Super+Alt+drag only while Snipdeck runs; otherwise the combination stays GNOME’s window move.
2. Log out and back in after installing Snipdeck and after every GNOME upgrade. GNOME Shell cannot load an extension in place on Wayland, because it is the compositor holding your session.
3. Check the extension’s state:

gnome-extensions info [email protected]

The state should be ACTIVE. If the command says the extension does not exist, it was not installed: install.sh installs it only when it runs inside a GNOME session. If the extension is installed but not enabled, run gnome-extensions enable [email protected] and log out and back in. If the state is OUT OF DATE, the installed extension does not list your GNOME version and GNOME refused to load it: install a newer Snipdeck.

Still missing on GNOME Wayland, even with the extension: when you drag a snip, GNOME moves it and does not tell Snipdeck where it landed, so its position is not remembered across restarts.

Snips do not stay on top, and there is no drag gesture (other Linux desktops)

Symptom. On KDE, sway, Hyprland or another Wayland desktop, snips open wherever the compositor puts them, do not float above other windows, and appear in the window list. Holding a modifier and dragging does nothing.

Why it happens. A Wayland program cannot choose where its windows go, ask where they are, or keep them above others; the compositor decides. Snipdeck does not yet use the wlr-layer-shell protocol that KDE and the wlroots compositors offer for this. The modifier+drag gesture would need a global mouse hook, which Linux grants only by reading /dev/input, in effect a system-wide keylogger, and Snipdeck will not ask you to allow that.

What to do. Capture with the hotkeys or the New button in the gallery. Region capture, the freeze overlay, OCR, dragging and the context menu all work.

No tray icon (GNOME)

Symptom. Snipdeck runs, but there is no icon in the top bar.

Why it happens. GNOME has no tray of its own. Snipdeck’s tray icon needs libayatana-appindicator and, on GNOME, the AppIndicator extension.

What to do. Install both, then log out and back in. Without a tray, Snipdeck still works:

• Closing the gallery window quits Snipdeck, because there would be nothing to bring it back.
• Starting Snipdeck again while it runs brings its window back instead of starting a second copy.

A screen-sharing dialog appears when you snip (Linux, Wayland)

Symptom. The first snip asks for permission to share your screen, or a screen-sharing indicator flashes in the top bar.

Why it happens. On Wayland Snipdeck reads the screen through the desktop’s ScreenCast portal. The desktop asks once; the indicator shows only while a snip is taken.

What to do. Approve the dialog. A snip taken with Super+Alt+drag on GNOME does not use the portal at all; the extension captures it inside GNOME Shell.

Email, the image editor or Open link do nothing (Linux)

Symptom. New email with the snip attached or Open in the system image editor shows an error asking you to install xdg-utils, or Open link after an upload does nothing.

Why it happens. On Linux these hand the work to xdg-email and xdg-open, from the xdg-utils package.

What to do. Install xdg-utils. The upload itself does not need it; the link is copied to the clipboard either way.

Win+drag does not trigger the first time (Windows)

Symptom. After Snipdeck has been idle for a while, the first Win+drag, often on a second monitor, does nothing. The next one works.

Why it happens. Snipdeck starts captures from a Windows low-level input hook. Windows gives these hooks a strict time limit, and an idle process at normal priority can have the first event after a quiet period dropped.

The fix is built in. Snipdeck raises its own process to high priority at startup so the hook answers in time. If you still see a missed first drag:

• Drag again.
• Make sure only one Snipdeck is running. Snipdeck allows one per session, but a stuck process from an earlier session can interfere; check the tray and Task Manager.

Win+drag does not work over an administrator window (Windows)

Symptom. Win+drag works everywhere except over a window that runs as administrator, such as an elevated terminal.

Why it happens. Snipdeck runs at your normal user level. Windows does not pass input aimed at an elevated window to the hooks of a normal-level program; this protects you from keyloggers.

What to do. Right-click the tray icon and choose Run as administrator. Snipdeck restarts elevated after one UAC prompt. This lasts until you quit it; the next start is normal again.

A snip is black or blank (Windows)

Symptom. A snip is solid black, or one window in it (a hardware-accelerated browser, a video player, a game) is black while the rest captured fine. This is most common on laptops with two GPUs.

Why it happens. Snipdeck captures the monitor with DXGI Desktop Duplication, which reads the frame Windows composed on the GPU. When that is unavailable, or when the frame comes back fully black, it falls back to GDI.

What to do:

• Dismiss any UAC prompt before you snip.
• Protected video stays black with every capture method. Snipdeck does not work around it.
• For black windows on a two-GPU laptop, move the window to your main display or update the GPU driver so Desktop Duplication works on that output.

Your antivirus or SmartScreen warns about Snipdeck (Windows)

Symptom. Windows Defender, SmartScreen or a company security agent warns about snipdeck.exe, quarantines it, or blocks it from starting at login.

Why it happens. A snipping tool does things that look suspicious to heuristics: it installs global mouse and keyboard hooks, captures the screen, and starts at login. A new, unsigned program from an independent developer can also trigger reputation warnings such as SmartScreen.

What Snipdeck does to avoid it:

• Launch at login uses a Startup shortcut, not the registry Run key that security tools flag most often.
• The program is not packed. Executable packers are associated with malware. Snipdeck is a normal, unpacked Rust binary, made smaller only by link-time optimization and symbol stripping.
• It runs at your normal user level. Running as administrator is a one-time action you choose from the tray.

What to do:

• If SmartScreen says “Windows protected your PC”, choose More info → Run anyway for the official file from the Releases page.
• If a security agent quarantines it, add an exception, or build it yourself from source so you control the exact program (see Installation).
• The source is open, so you or your security team can read it and build the same program.

OCR finds no text

Symptom. OCR + Clipboard finds nothing, or a snip’s text does not show up in search.

On Windows, Snipdeck uses the built-in Windows.Media.Ocr engine:

• The script’s language is not installed. OCR uses the languages in your Windows profile and falls back to English (US). Add the language under Settings → Time & language → Language & region and make sure its optional OCR feature is installed.
• The snip is very small. Snipdeck enlarges tiny snips before OCR, but a single word or character can still come back empty. Capture a slightly larger area.

On Linux, Snipdeck uses tesseract:

• tesseract is not installed. Without it OCR is skipped rather than failing. Install it from your distribution (for example tesseract-ocr on Debian and Ubuntu).
• The language data is missing. Snipdeck asks tesseract for Turkish and English when their data is installed, and otherwise uses tesseract’s default. Install the language packs you need, for example tesseract-ocr-tur.

On both:

• There is no printed text: a photo, an icon, a stylized logo or handwriting.
• The text is low-contrast or tiny on screen. Zoom in before you capture.

OCR + Translate fails

Symptom. OCR works, but OCR + Translate shows an error.

Why it happens. Translation is not local. After OCR, the recognized text goes to Google Translate at translate.googleapis.com, and that one network request is where it can fail:

• No internet connection. OCR works offline; translation does not.
• A firewall or proxy blocks the request. Allow translate.googleapis.com over HTTPS.
• The service throttled you. This is a public endpoint without a key. Normal use is light, so this is rare; wait and try again.
• The request timed out. Snipdeck gives up after a short wait so a hung request cannot block it. Try again.

The first time you use OCR + Translate, Snipdeck asks whether the text may be sent. Until you agree, nothing is sent. See Privacy and security.

An upload fails

Symptom. The upload window says Upload failed.

Why it happens. The window shows the reason the host or the network gave. Common ones:

• Imgur rejected the request (HTTP 403): the Client-ID in settings.json may be wrong. Check imgur_client_id.
• Imgur quota exceeded (HTTP 429): try again later.
• Failed to connect: no network, or a firewall blocks the host.
• The host’s answer has no {json:…} (or another field): your own server answered, but not in the shape its .sxcu file describes. The server may have changed; get a fresh .sxcu file from it.

What to do. Fix the cause and press Try again; the snip is still there. If you hid the window during the upload, it comes back by itself with the result.

If a .sxcu file is refused when you add it, the message says what it needs that Snipdeck does not support. See Sharing and export.

Your settings were reset

Symptom. Snipdeck starts with default settings and shows “Settings could not be read and were reset”.

Why it happens. settings.json was not valid JSON, usually after a hand edit. Snipdeck started with the defaults and moved your file to settings.json.bak, so it would not be overwritten.

What to do. Quit Snipdeck, fix the mistake in settings.json.bak (often a missing comma or quote), and rename it back to settings.json. See Settings.

See also

• Installation: installing on Windows and Linux
• Capture shortcuts: every capture gesture per platform
• OCR and OCR + Translate: how text recognition and translation work
• Privacy and security: what stays local and what leaves your machine
• FAQ: short answers to common questions