Troubleshooting

The common problems and how to fix them. If yours isn't here, open an issue; please never paste clip contents or secrets into it.

The hotkey doesn't open the picker

Another app owns it. If Ctrl Shift Space is taken (some input-method switchers and launchers use it), Settings shows "… is already in use by another app". Pick another combination in Settings → Shortcuts, e.g. Ctrl Alt V or Win Shift V.
ClipTrail isn't running. Check for the tray icon. Turn on Start with Windows so it's always there.
Linux on Wayland: most Wayland compositors have no global-shortcut protocol for apps to use. Bind a desktop-environment shortcut to cliptrail --picker instead — it opens the picker in the running app (KDE: System Settings → Shortcuts → Custom Shortcuts → Command; GNOME: Settings → Keyboard → Custom Shortcuts). On an X11 session the built-in hotkey works as on Windows.

Paste-back doesn't paste

The clip is always put on your clipboard first, so Ctrl V works as a fallback. If the automatic paste doesn't happen:

Elevated (administrator) windows: Windows blocks normal apps from typing into them. Paste manually.
Terminals: most Linux terminals paste with Ctrl Shift V. ClipTrail detects common terminal windows on X11 and sends that combination automatically; if yours isn't detected, press it yourself. (Windows Terminal and PowerShell accept Ctrl V.)
Wayland: paste-back is X11-only. The picker shows "Copied — press Ctrl+V to paste".
Games and remote desktops may ignore synthetic keystrokes. Paste manually.
Focus moved: if you clicked another window while the picker was open, it pastes into the window that had focus when the picker opened, or not at all if that window closed.

Copies aren't being saved

Capture is paused. The sidebar shows Paused instead of Capturing; resume it there or from the tray.
The app is excluded (Settings → Privacy → Excluded apps), or it marks its copies as private, as password managers do. That's on purpose.
It was a secret. Codes and keys are saved as Sensitive, masked, and deleted after their lifetime. Look under Sensitive.
It was huge. Text clips over 2 MB are skipped.
Linux on GNOME (Wayland): GNOME doesn't offer the clipboard protocol ClipTrail needs, so it falls back to X11 and only sees copies while an X11 (XWayland) window has focus. KDE Plasma, Sway and Hyprland work natively; an X11 session also works.
macOS: copies from apps that mark them concealed or transient (password managers, one-time fields) are skipped on purpose. Otherwise capture is automatic — check that capture isn't paused.

macOS

"ClipTrail can't be opened" on first launch: the build isn't notarized by Apple. Open System Settings → Privacy & Security and click Open Anyway, then launch it again (on macOS 14 and earlier, right-click ClipTrail in Applications → Open also works).
"ClipTrail is damaged and can't be opened": that's the download quarantine flag on an unnotarized app, not a broken file. In Terminal run xattr -dr com.apple.quarantine /Applications/ClipTrail.app, then open it again.
Picking a clip copies it but doesn't paste: paste-back needs Accessibility permission. Open System Settings → Privacy & Security → Accessibility and allow ClipTrail (Settings in the app has a button that jumps straight there). Until then, press Cmd V yourself.
The picker doesn't open: the default hotkey is Cmd Shift Space. If you changed it or it clashes with another app, rebind it in Settings → Shortcuts.
No Dock icon: that's intended — ClipTrail is a menu-bar app. Use the menu-bar icon or the hotkeys.

Sync doesn't connect

Pairing seems stuck, or a device shows as offline. Work through these in order:

Same network? Both devices must be on the same Wi-Fi or LAN. Mobile data, a different Wi-Fi band on a separate network, or a guest network won't work.
Hub running? Settings → Devices on the hub should say Ready on 192.168.x.x:47821. If it says Not running, click Retry. Another program, or clipd sync host, may be using the port; change it under Network → Port.
Windows firewall: allow ClipTrail on Private networks: Windows Security → Firewall & network protection → Allow an app through firewall.
Network set to Public: Windows blocks incoming connections on Public networks. Settings → Network & internet → Wi-Fi → your network → Network profile type → Private.
Wi-Fi client isolation: many office, hotel, café and guest networks stop devices from seeing each other ("AP isolation"). Use your home network, or a hotspot from a third device.
VPN: a VPN on either device can route local traffic away. Allow LAN access in the VPN's settings ("local network sharing") or pause it while pairing.
Laptop asleep: the hub must be awake. Devices catch up automatically when it wakes.
Check code didn't match or the code expired: revoke the device if it was added, then click Pair a phone again for a fresh code.

clipd sync status shows the last error a device ran into, which usually says which of these it is.

Android: capture stops after a while

This is almost always the phone's battery manager stopping the app. On Samsung:

Settings → Apps → ClipTrail → Battery: Unrestricted.
Settings → Battery → Background usage limits: add ClipTrail to Never sleeping apps and turn off Put unused apps to sleep.
Check the accessibility service is still on (Settings → Accessibility → Installed apps). Android may turn it off after an app update or a crash.
Keep the "capturing" notification; dismissing or blocking it lets Android stop the service.

Accessibility switch greyed out? That's Android's restricted settings. For a copy that wasn't caught, tap the Save clipboard tile. More in Android setup.

Windows says "Windows protected your PC"

Pre-release installers aren't code-signed yet. Click More info → Run anyway. Builds are made by GitHub Actions from the public source.

Still stuck?

Quit and restart ClipTrail from the tray.
Run clipd stats to check the data folder opens.
Open an issue with your OS, version and what you tried. Logs never include clip content, but check before you paste them anyway.