10. PinSlip FAQ and Troubleshooting

8/1/2026

10. FAQ

This chapter collects the most common questions and troubleshooting steps.
Can't find an answer? Let us know on GitHub Issues.

Install and Launch

macOS Says "App Is Damaged"

Cause: The current build is unsigned (from v1.0.1 onward, signing removes the need for this workaround).

Pick either workaround:

  1. In Applications, right-click PinSlip → Open.

  2. In Terminal: xattr -cr /Applications/PinSlip.app.

Global Shortcut Doesn't Respond on Linux

Cause: Under a Wayland session, global shortcuts don't reach native windows.

Fix: Log in using an X11 session; X11 behaves as expected.

GNOME Hides the Tray Icon

Cause: GNOME doesn't show app indicators by default.

Fix: Install the AppIndicator and KStatusNotifierItem Support extension.

First Launch Is Slow

Cause: The Go service compiles for the first time + the index rebuilds in full.

Note: The second launch is instant. An empty vault usually takes a few seconds; a vault with thousands of notes can take 1–2 minutes.

Notes Missing / Off-Screen

A Note Drifted Off-Screen

Cause: An external monitor was disconnected, or display resolution changed.

Fix: Reopen the app → PinSlip automatically returns the note to the visible area.

The Main Window Is Gone

Fix:

  • Left-click the PinSlip tray icon → toggle the window.

  • Press Ctrl+Shift+N to bring up Quick Capture.

  • Restart the app.

Not in the Windows Taskbar Either

Fix: Every note has its own taskbar icon; if it's not there, check whether the tray is hiding icons.

Delete and Recover

I Deleted Something by Mistake

Fix: Drag the file back into notes/ from .trash/; PinSlip's watcher detects it and rebuilds the index.

I Deleted a Whole Folder

Fix: Drag the folder back into notes/ from .trash/<tree>/.

I Want to Hard-Delete a Note (Skip the Recycle Bin)

Fix: Delete the file directly from .trash/ (bypassing PinSlip's delete logic).

Not generally recommended — the recycle bin exists as your safety net.

Search

Some Keywords Don't Return Results

Troubleshooting:

  • Strings of pure symbols are often missed.

  • Try tag or title words (they have the highest search weight).

  • Keywords buried in the body have lower weight and may not rank first.

Too Many Search Results

Fix: Add more keywords; or search by tag.

Markdown and Images

Pasted Images Don't Show

Troubleshooting:

  • Check the permissions on <vault>/attachments/.

  • Whether your external editor (Obsidian / VS Code) supports relative paths like ../attachments/.

  • Whether the path inside <img> contains Chinese characters or spaces (it shouldn't).

Task Checkboxes Won't Toggle

Troubleshooting:

  • The cursor needs to be over the checkbox square itself.

  • Is the note currently collapsed? (In collapsed state, checkboxes can still be clicked but the area scrolls to the target.)

The Font Size Buttons Disappeared

Cause: The window is too narrow; lower-priority buttons were hidden.

Fix:

  • Widen the window.

  • Open the ⋯ menu and look for Font size zoom.

Git Sync

Authentication Failure

Troubleshooting:

  • Is the token expired?

  • Does the repo URL end with .git?

  • Do you have write permission?

  • Is the username spelled correctly?

Sync Is Stuck

Cause: Network or remote issues.

Fix:

  • Check lastError on the status panel.

  • Exponential backoff (1m → 5m → 15m) is normal behavior.

Sync Fails Repeatedly

Troubleshooting:

  • Can the network reach GitHub / GitLab / cnb?

  • DNS pollution? Try editing your hosts file.

  • Pull fails from inside China? Consider switching to cnb or self-hosted Gitea.

"Conflict Pending" Appears

Fix: Open the conflicted note → choose Use all local / Use all remote / edit manually → Save resolution.

See 06-Sync → Conflict Resolution.

MCP

Client Can't Connect to MCP

Troubleshooting:

  • Check that <vault>/.pinslip/mcp.json exists.

  • Is the pid alive (matching the running PinSlip process)?

  • Is the MCP switch on in Settings?

  • Did the client URL use 127.0.0.1 instead of localhost?

Tool Call Returns 404

Cause: The MCP switch is off, or the service isn't running.

Fix:

  • Settings → MCP Service → turn the switch on.

  • Restart PinSlip.

Tool Call Timeout

Fix:

  • Check whether the Go service is stuck (restart PinSlip).

  • Check whether a large batch of notes is rebuilding the index.

Browser Extension

Extension Can't Reach the Desktop

Troubleshooting:

  • Is PinSlip running on the desktop?

  • Does the port in the options page match the port in mcp.json (default 17639, may differ)?

  • Try the Reconnect probe button.

PinSlip Doesn't Show in the Right-Click Menu

Troubleshooting:

  • Did you enable the "context menus" permission for the extension?

  • Is the page one where injection is blocked (Chrome Web Store / settings pages, etc.)?

Performance

Large Vault Opens Slowly

Fix:

  • Check whether .pinslip/pinslip.db is being held open by another program (it shouldn't be).

  • A few thousand notes is generally fine.

  • Use the recycle bin regularly to clear out notes you no longer need.

Editing Lags

Troubleshooting:

  • Is a single note very long? Split it or archive the content to a separate file.

  • Is the browser extension continuously reading and writing the disk?

Other

macOS Tray Icon Size Is Wrong

Note: v1.0.0 had a "huge icon bursting the menu bar" issue; v1.0.1 fixes it. Upgrade to the latest version.

How to Fully Uninstall

  1. macOS: drag to the Trash.

  2. Windows: Settings → Apps → Uninstall.

  3. Linux: sudo apt remove pinslip or just delete the AppImage.

  4. Delete the vault directory (back it up first).

Who Owns Your Data?

You do. PinSlip is just a shell. Your notes always exist as Markdown files on your disk.
Even if PinSlip went away tomorrow, any editor — Obsidian, VS Code, Typora — could open them.
That's PinSlip's design philosophy, baked in from day one.