Troubleshooting
Common issues and their solutions.
Installation Issues
macOS: "App is damaged" or Security Warning
Release downloads are signed and notarized, so Gatekeeper opens them without a
warning. If macOS still reports the app as damaged, download
mahpastes-macos-universal.zip again from the
Releases page and extract it
with Finder or ditto -x -k; tools that drop extended attributes or symlinks
while unpacking break the signature.
An unsigned app that was downloaded or copied from another Mac, such as an unsigned build artifact, is blocked instead. Allow it once:
- Try to open the app, then dismiss the warning
- Open System Settings > Privacy & Security
- Click Open Anyway next to the message about mahpastes and confirm
- The app launches and macOS remembers the choice
On macOS 14 and earlier you can instead right-click the app, select "Open" and click "Open" in the dialog. Or clear the download quarantine via Terminal:
xattr -cr /Applications/mahpastes.app
macOS: App Won't Open (Apple Silicon)
The release app is a universal build that runs natively on Intel and Apple
Silicon and needs macOS 13 or later. Check About This Mac for the macOS
version, and make sure you copied the whole mahpastes.app out of the archive.
Windows: SmartScreen Warning
The Windows build is not code-signed, so SmartScreen may show "Windows
protected your PC" on first launch. Click More info, then Run anyway.
On ARM PCs, use mahpastes-windows-arm64-installer.exe or
mahpastes-windows-arm64.zip. The x64 installer refuses to install on ARM
("can't be installed on the current Windows architecture"); the x64 zip runs,
but under emulation.
Linux: App Won't Start
The release build needs GTK 3, WebKitGTK 4.1 and glibc 2.39 or newer (Ubuntu
24.04, Debian 13, Fedora 40 and later). An error such as libwebkit2gtk-4.1.so.0: cannot open shared object file means the library is missing: install
libwebkit2gtk-4.1-0 (Debian/Ubuntu) or webkit2gtk4.1 (Fedora). On older
distributions, such as Ubuntu 22.04, build from source instead; the build falls
back to WebKitGTK 4.0 there.
If the app does not appear in the application menu after ./install.sh, log
out and back in, or check that ~/.local/share/applications/mahpastes.desktop
exists.
Runtime Issues
Paste Not Working
Symptoms: Pressing Cmd+V doesn't add clips.
Solutions:
- Ensure mahpastes window is focused
- Click outside any text field -- paste is disabled when a search box, form input, or text area is focused (the keystroke goes to the field instead)
- Check if viewing Archive (can't paste to archive)
- Verify clipboard has content
- Try drag and drop instead
Clips Not Appearing
Symptoms: Paste or drop works but clip doesn't show.
Solutions:
- Refresh the gallery (switch tabs and back)
- Check if accidentally archived
- Check if expiration is set too short
- Restart mahpastes
Database Locked Error
Symptoms: Operations fail with database locked error.
Solutions:
- Close any other apps accessing the database
- Close SQLite tools if open
- Restart mahpastes
- If persists, delete WAL files (quit mahpastes first). macOS path shown -- substitute your platform's path from Data Storage:
rm ~/Library/Application\ Support/mahpastes/clips.db-wal
rm ~/Library/Application\ Support/mahpastes/clips.db-shm
"Another mahpastes instance is already running"
Symptoms: Launching mahpastes shows this error (in a dialog on Windows and macOS, on the terminal on Linux or when started from one) instead of opening a window.
A second launch normally just brings the running window to the front. You see this error only when the process holding the data directory is not a desktop window that can take over, usually:
- The headless server
mahpastesdis running against the same data directory -- stop it, or give one of them a differentMAHPASTES_DATA_DIR - The running instance is still starting up or is hanging -- wait a moment, or end the process named in the message
Closing the window does not quit mahpastes
Symptoms: After closing the window, watch folders still import, or mahpastes does not appear to start again.
Keep running when the window is closed is on (the default on macOS), so mahpastes is still running without its window. Launching it again (or clicking its Dock icon on macOS) shows the window. To quit, use Cmd/Ctrl + Q or Quit mahpastes in the menu drawer, or turn the setting off under Settings > Background & Startup (takes effect after a restart). See Background & Startup.
mahpastes starts without a window at login
Launch at login with Start in the background is on. Launch mahpastes again (or click its Dock icon on macOS) to show the window, or turn Start in the background off under Settings > Background & Startup.
High Memory Usage
Symptoms: App uses excessive memory.
Solutions:
- Delete large clips you don't need
- Reduce number of clips in gallery
- Archive old clips
- Restart mahpastes periodically
Watch Folder Issues
Files Not Importing
Symptoms: New files in watched folder don't appear.
Checklist:
- ✓ Watch folder is not paused
- ✓ Global watching is not paused
- ✓ Folder path still exists
- ✓ File matches filter settings
- ✓ File is not hidden (starts with .)
Test filter:
- Temporarily set filter to "All files"
- If imports work, adjust your filter
Files Importing but Not Appearing
Symptoms: Import notification shows but clip isn't visible.
Solutions:
- Check Archive view (if auto-archive enabled)
- Refresh the gallery
- Check for errors in notifications
Original Files Not Deleted
Symptoms: Files import but remain in folder.
Causes:
- File was open in another app
- Permission issues
- Import failed silently
Solutions:
- Close apps that might have the file open
- Check folder permissions
- Look for error notifications
Watch Folder Shows Error
Symptoms: Folder shows an amber "Folder not found" badge.
Causes:
- Folder was deleted or moved
- Permission changed
- Network drive disconnected
Solutions:
- Re-add the folder with correct path
- Check folder exists and is accessible
- Remove and re-add the watch
Editor Issues
Image Editor Tools Not Working
Symptoms: Can't draw on canvas.
Solutions:
- Ensure a tool is selected (check toolbar highlight)
- Select a tool by clicking its button in the toolbar
- Check color isn't same as background
- Increase stroke width if very thin
Undo/Redo Not Working
Symptoms: Cmd+Z doesn't undo.
Solutions:
- Ensure editor window is focused
- Check if at start of history (nothing to undo)
- Try clicking canvas first, then shortcut
Text Not Visible
Symptoms: Text tool adds text but can't see it.
Solutions:
- Change text color (may be same as background)
- Increase font size
- Click in a visible area of the image
Performance Issues
Slow Gallery Loading
Symptoms: Gallery takes long to load.
Causes:
- Many clips in database
- Large images
- Slow disk
Solutions:
- Archive old clips
- Delete unused clips
- Set expiration for temporary clips
Slow Image Editor
Symptoms: Editor is laggy when drawing.
Causes:
- Very large image
- Many history states
- Low system resources
Solutions:
- Work with smaller images when possible
- Save periodically (resets history)
- Close other resource-heavy apps
Data Issues
Lost Clips
Symptoms: Clips disappeared unexpectedly.
Possible causes:
- Expiration triggered -- expiration is set per-clip at upload time and runs on a 1-minute cleanup cycle
- Accidentally deleted
- Database corruption (rare)
Prevention:
- Use "Never" expiration for clips you want to keep
- Archive important clips for long-term storage (note: archiving does not cancel expiration)
- Regular backups
Corrupted Database
Symptoms: App crashes, errors about database, or a "Could not open the database" dialog at startup.
Solutions:
- Restore from backup if available
- Try database recovery (quit mahpastes first, macOS path shown -- substitute your platform's path from Data Storage):
cd ~/Library/Application\ Support/mahpastes/
sqlite3 clips.db ".recover" | sqlite3 recovered.db
mv recovered.db clips.db - Delete database and start fresh (last resort)
Transfer Issues
Drag-Out Not Working
Symptoms: Can't drag clips out of mahpastes into other apps.
Solutions:
- Drag-out is supported on macOS, Windows and Linux. On Linux the drop target must accept a
text/uri-listfile drop (Dolphin, Nautilus and most GTK/Qt apps do); results can vary by compositor and receiving app. See Drag and Drop. - Hover the grip handle on the clip card for at least 1 second to arm the drag.
- Wait for the handle to finish the preparation animation before dragging.
- If the handle shows a spinner, the temp file is still being prepared. Wait until it returns to the grip icon.
Copy File Not Working
Symptoms: "Copy File" from the card menu doesn't paste a file in Finder (macOS), Explorer (Windows) or the Linux file manager.
Solutions:
- Copy File is supported on macOS (NSPasteboard), Windows (PowerShell) and Linux. If the copy itself fails, for example in a Linux session where no clipboard is reachable, mahpastes shows "Failed to copy file." instead of a success message.
- On Linux the file is offered as one clipboard type only, picked from
XDG_CURRENT_DESKTOP:x-special/gnome-copied-fileson Cinnamon, MATE, Xfce, Budgie and Pantheon (Nemo, Caja, Thunar and elementary Files read only that type),text/uri-listeverywhere else (Dolphin, Nautilus 43 and later, PCManFM, browsers and chat apps). Pasting into an app that wants the other type, or into a terminal, pastes nothing. Paste before quitting mahpastes: the clipboard offer ends when the app exits. - On Windows, ensure no policy blocks PowerShell clipboard access.
- Try "Copy Contents" instead if you only need the raw data (text or image).
Platform-Specific Issues
Window Opens in the Wrong Place or at the Wrong Size
Issue: After changing monitors or display scaling, the window opens somewhere awkward.
Solution: Quit mahpastes, remove the window entry from desktop-prefs.json in the data directory (or delete the file, which also resets Keep running when the window is closed), and start it again. The window opens centred at its default size, and the new placement is remembered from then on.
System Notifications Do Not Appear
Issue: System Notifications is on, but nothing shows when a watch folder imports in the background.
Solution:
- Open Settings → System Notifications. If it says "Not available", the reason follows: on macOS allow mahpastes under System Settings → Notifications (the bare binary that
wails devruns cannot notify at all; a built.appcan); on Linux make sure a notification daemon is running. - Click Send Test Notification. If nothing appears, Focus / Do Not Disturb / Focus assist is probably hiding it.
- Notifications only appear while the window is unfocused, and similar events are combined, so a burst of imports shows as one notification after a couple of seconds.
See System Notifications.
macOS: Drag and Drop from Safari
Issue: Dragging images from Safari doesn't work.
Solution: Right-click and save image first, then drag file.
Import Folder: Files Marked for Deletion Are Not Deleted
Issue: The Import Folder summary reports files it could not delete, and they are still in the folder.
The wizard moves deleted originals to the Trash (macOS, Linux) or the Recycle Bin (Windows). When a file cannot be moved there, the wizard leaves it in place and reports it, instead of deleting it permanently.
Causes:
- Linux: the folder is on a mount without trash support, such as
/tmpor another tmpfs or system-internal mount, or the mount does not allow a.Trash-<uid>folder. - Windows: the folder is on a network share, a mapped network drive or a removable drive. These have no Recycle Bin. Paths longer than 259 characters are also refused.
Solutions:
- Delete the remaining files yourself in your file manager.
- Move the folder to a local disk before importing it.
On Linux, moving files to the Trash needs the gio tool (glib2; the libglib2.0-bin package on Debian and Ubuntu). Without it, the wizard warns that deletion is permanent before you choose any deletes.
On Windows, a file too large for the Recycle Bin is still deleted permanently.
REST API Issues
Connection Refused
Symptoms: API calls fail with "connection refused."
Solutions:
- Verify mahpastes is running
- Open the menu drawer, click API and confirm the API is enabled. The server does not start with the app unless Start on launch is on
- Check the port matches your
MP_API_URL(defaulthttp://localhost:44557)
401 Unauthorized
Symptoms: API calls return 401.
Solutions:
- Check your
MP_API_KEYenvironment variable (or the fileMP_API_KEY_FILEnames) holds the right key - Verify the key has not been revoked (menu drawer > API)
- Confirm the key prefix is
mp_
403 Forbidden
Symptoms: API calls return 403.
Solutions:
- The key may lack the required role for the requested operation
- Scoped keys can only access clips within their assigned tag -- verify the key's scope (menu drawer > API)
Port Already in Use
Symptoms: API fails to start, logs show "address already in use."
Solutions:
- Change the API port (menu drawer > API)
- Find and stop the process using the port:
lsof -i :44557
CLI (mp) Issues
"MP_API_KEY environment variable (or MP_API_KEY_FILE) is required"
Symptoms: Any mp command fails immediately with exit code 3.
Solution: Export your API key before running commands:
export MP_API_KEY=mp_your_key_here
Or keep the key in a file and point MP_API_KEY_FILE at it:
export MP_API_KEY_FILE=~/.config/mahpastes-key
Add the export to your shell profile (~/.zshrc or ~/.bashrc) for persistence.
"MP_API_KEY_FILE ... is empty" or "must contain only the API key"
Symptoms: Any mp command fails immediately when MP_API_KEY_FILE is set.
Solution: The file must hold just the key, such as mp_abc123..., optionally followed by a newline. Remove blank or extra lines, spaces inside the key, and quotes.
"Cannot connect to mahpastes"
Symptoms: Commands fail with the message "Cannot connect to mahpastes. Is the app running with the API enabled?"
If MP_API_URL points at a host that does not answer at all, this message appears after MP_TIMEOUT (default 30s).
Solutions:
- Verify the mahpastes desktop app is running
- Confirm the API is enabled (menu drawer > API). Turn on Start on launch there so it starts with the app every time
- If using a custom URL, check
MP_API_URL:export MP_API_URL=http://localhost:44557
mp api status
"Timed out waiting for mahpastes"
Symptoms: A command fails with exit code 2 after about 30 seconds.
Cause: mp connected, but the server did not start responding within MP_TIMEOUT (default 30s). This usually means the app is hung or something else is listening on that port.
Solutions:
- Check that
MP_API_URLpoints at mahpastes and that the app is responsive - On a slow network link, raise the limit, for example
export MP_TIMEOUT=2m
"Authentication failed. Check MP_API_KEY (or MP_API_KEY_FILE)."
Symptoms: Commands fail with exit code 3.
Solutions:
- Verify
MP_API_KEY(or the fileMP_API_KEY_FILEnames) holds a valid, non-revoked key - Create a new key (menu drawer > API) if needed
- Check for extra whitespace or quotes in the key value
Plugin Issues
Plugin Auto-Disabled
Symptoms: Plugin stops running; shows as disabled.
Cause: After 3 consecutive errors, plugins are automatically disabled.
Solutions:
- Check the plugin logs for error details
- Fix the underlying issue in the plugin script
- Re-enable the plugin in the Plugins panel
Permission Denied
Symptoms: Plugin fails with a permission error.
Cause: The plugin tried to access network or filesystem resources without declaring them in its manifest.
Solution: Add the required permission to the plugin's manifest:
network = { ["example.com"] = {"GET", "POST"} }for HTTP requests (specify allowed domains and methods)filesystem = { read = true }orfilesystem = { read = true, write = true }for file accessclipboard = truefor clipboard writes
Sandbox Timeout
Symptoms: Plugin execution is killed mid-run.
Cause: Plugins have execution time limits:
- Event handlers: 30 seconds
- UI actions (synchronous): 5 minutes
- UI actions with
async = true: 5 minutes, but run in a background goroutine so the UI is not blocked
Solutions:
- Optimize long-running plugin logic
- For actions that genuinely need time, set
async = truein the action manifest so execution happens in the background and the UI stays responsive
Tag Serve Issues
401 on /_api Requests
Symptoms: JSON API calls to a served tag return 401 Unauthorized.
Cause: The /_api endpoints use cookie authentication. The _mp_serve_key cookie is set when you visit the served page.
Solution: Load the served tag's page in a browser first -- the cookie is set automatically. Subsequent /_api requests from that page will authenticate via the cookie.
File Upload Rejected
Symptoms: POST /_api/_upload returns 400 or 403.
Checklist:
- File must be under 10 MB
- Path in the
tagform field must not contain..or_apisegments - API access must be
readwrite(notreadornone) - Request must include a valid
_mp_serve_keycookie
JSON API Returns 404
Symptoms: GET /_api/... returns 404 for all paths.
Cause: API access is set to "none" (the default).
Solution: Stop and restart the tag server with API access enabled:
- Read-only:
--api-access read - Full CRUD:
--api-access readwrite
In the UI, set the API access dropdown when starting the serve.
Getting Help
If issues persist:
- Check GitHub Issues for known problems
- Search closed issues for solutions
- Open a new issue with:
- OS and version
- mahpastes version
- Steps to reproduce
- Error messages (if any)
- The log file: Maintenance → Open Log Folder opens the folder with
mahpastes.log(see Log Files); if the app does not start, find it underlogs/in the data directory - Screenshots (if relevant)