Troubleshooting Guide

Solutions to common issues with Handrive.

Installation Issues

macOS: "App is damaged" or "Cannot be opened"

macOS shows a security warning when trying to open Handrive.

Solution 1: Right-click to open

  1. Right-click (or Control+click) on Handrive in Applications
  2. Select "Open" from the context menu
  3. Click "Open" in the dialog

Solution 2: System Preferences

  1. Open System Preferences > Privacy & Security
  2. Scroll to the bottom
  3. Find the message about Handrive being blocked
  4. Click "Open Anyway"

Solution 3: Remove quarantine attribute

xattr -dr com.apple.quarantine /Applications/Handrive.app

Windows: SmartScreen Warning

Windows shows "Windows protected your PC" warning.

  1. Click "More info"
  2. Click "Run anyway"

Linux: Missing Dependencies

Application fails to start with library errors.

# Debian/Ubuntu
sudo apt install -y libssl3 libwebkit2gtk-4.1-0 libgtk-3-0

# Fedora/RHEL
sudo dnf install -y openssl webkit2gtk4.1 gtk3

# Arch
sudo pacman -S openssl webkit2gtk-4.1 gtk3

Login Problems

OTP Not Received

No email arrives after requesting OTP.

  • Check spam/junk folder — OTP emails sometimes get filtered
  • Check email address — Verify you typed it correctly
  • Wait a few minutes — Emails can be delayed
  • Request a new OTP — Only the latest OTP is valid
  • Try personal email — Some corporate email blocks automated messages

OTP Invalid or Expired

  • OTPs expire after 10 minutes
  • Only the latest OTP is valid
  • Request a new code if yours has expired

Google OAuth Fails

  • Check browser popup — OAuth opens in default browser
  • Allow popups — Enable popups for handrive.app
  • Clear browser cache — Old OAuth sessions can cause issues
  • Try incognito mode — Rules out extension conflicts

Connection Issues

Understanding Connection Status

The connection indicator next to the logo shows your status:

ColorStatusMeaning
🟢 GreenConnectedYou're online and connected
🟡 YellowReconnectingAttempting to reconnect
🔴 RedOfflineNo connection to Handrive services

Stuck on "Reconnecting"

  1. Check your internet connection (can you browse websites?)
  2. Wait a minute for automatic reconnection
  3. Try logging out and back in
  4. Restart Handrive
  5. Check if a firewall is blocking the app

Completely Offline

  1. Verify your internet works
  2. Check if Handrive services are down (try again later)
  3. Ensure Handrive is allowed through your firewall
  4. Try a different network

Firewall Settings

  • macOS: System Preferences → Security & Privacy → Firewall → Allow Handrive
  • Windows: Windows Security → Firewall → Allow an app → Handrive

Offline Mode

When offline, you can still:

  • Browse your local shares
  • View previously loaded file lists
  • Access files stored on your device

You cannot:

  • Browse remote shares
  • Transfer files to/from others
  • Sync changes

Sync Issues

Devices Not Syncing

  1. Check both devices are online — Sync requires both devices connected
  2. Check share membership — Both devices must have the same account
  3. Force rescan — Right-click share > "Rescan"
  4. Restart Handrive — Forces reconnection to sync service

Changes Not Appearing

  • Rescan the share — Right-click share > "Rescan"
  • Check file location — Files must be inside the shared folder
  • Check file permissions — Handrive needs read access to files

Conflict Files

Files appear with "(conflict)" in the name when the same file is edited on multiple devices.

  1. Open both versions
  2. Decide which to keep (or merge manually)
  3. Delete the version you don't want
  4. Rename the keeper to remove "(conflict)" suffix

Transfer Problems

Transfer Won't Start

  • Stuck on "Pending" — Too many transfers queued; wait for others to complete or cancel some
  • Stuck on "Connecting" — The other party may be offline, or network may be blocking P2P connections

Failed Transfers

Check the error message in transfer details. Common errors:

  • "Peer offline" — Wait for them to come back online and retry
  • "Connection lost" — Check your connection and retry
  • "File not found" — File was moved or deleted; verify it exists and rescan the share
  • "Disk full" — Free up disk space and retry
  • "Permission denied" — Check your role in the share (Viewers can't upload)

Slow Transfers

  • Check network connection — Run a speed test
  • Try wired connection — Instead of WiFi
  • Check VPN — VPNs can slow transfers
  • Many small files — Consider zipping files before transfer; many small files are slower than one large file

Partial Transfers

If a transfer fails partway through:

  • Some files may have transferred successfully
  • Check the destination for completed files
  • Retry the transfer for remaining files

Large File Transfers

  1. Be patient — Large transfers take time
  2. Stay online — Don't close Handrive or sleep your computer
  3. Use stable network — Wired connection recommended

Firewall/NAT Issues

Handrive uses UDP hole punching with STUN and ICE for P2P connections.

  • Enable UPnP for automatic port forwarding
  • Allow outbound HTTPS (443) and STUN (3478/UDP)
  • If UDP hole punching fails due to a restrictive firewall (e.g., symmetric NAT, strict corporate firewall), P2P connections won't work
  • Relay is available for enterprise users only — Contact enterprise@handrive.app if you need relay support for restricted networks
  • Contact your IT department if you're on a corporate network that blocks P2P

MCP Server Issues

MCP Server Won't Start

Not authenticated:

# Check authentication status (requires server running)
handrive auth status

# If not logged in, start server and authenticate
handrive serve &
handrive auth login otp your@email.com

The MCP server requires authentication before it can run. See the MCP Guide for setup instructions.

Claude Can't Connect to Handrive

  • Verify the path to handrive in Claude's config is correct
  • Ensure the binary is executable (chmod +x handrive)
  • Restart Claude Desktop after changing the config
  • Check that you're authenticated before MCP server starts

HTTP Server Port Issues

Port already in use:

# Find what's using the port
lsof -i :3001  # macOS/Linux

# Choose different port
handrive serve --port 3002

Performance Issues

High CPU Usage

  • Large folders — Folders with 10,000+ files require more processing
  • Antivirus conflicts — Add Handrive data folder to exclusions
  • Restart the app — Clears any accumulated state

High Memory Usage

  • Reduce number of shares
  • Close unused views
  • Restart periodically if running long-term

Large Folder Scanning

  • Initial indexing takes time — subsequent scans are faster
  • Don't share folders with 100,000+ files
  • Use SSD storage for faster disk I/O

Data & Recovery

Accessing Logs

  1. Click your profile in the sidebar
  2. Select About
  3. Click Open Logs or View Logs

Log File Locations

PlatformLocation
macOS~/Library/Logs/Handrive/
Windows%APPDATA%\Handrive\logs\
Linux~/.config/handrive/logs/

Reading Logs

Logs show timestamps, log levels, and messages:

2024-01-15T10:30:45.123Z INFO  Connected to signaling server
2024-01-15T10:30:46.456Z INFO  Share sync completed: 3 shares
2024-01-15T10:31:00.789Z ERROR Transfer failed: peer disconnected

To troubleshoot:

  1. Find the time when the problem occurred
  2. Look for ERROR lines near that time
  3. Read the message for clues

Note: Logs may contain file names and email addresses. Review before sharing if privacy is a concern.

Database Locations

PlatformLocation
macOS~/Library/Application Support/Handrive/handrive.db
Windows%APPDATA%\Handrive\handrive.db
Linux~/.config/handrive/handrive.db

Recovering from Database Issues

If the app won't start or shows database errors:

  1. Close Handrive completely
  2. Rename or delete the database file:
    # macOS
mv ~/Library/Application\ Support/Handrive/handrive.db \
   ~/Library/Application\ Support/Handrive/handrive.db.backup
  3. Restart Handrive
  4. Log in again
  5. Re-add your shares (files are still on disk)

Why It's Safe to Reset

Thanks to Handrive's asymmetric security model, it's completely safe to delete your local database and start fresh:

  • Your files are untouched — Shares are just pointers to folders on your disk
  • All data is local — Shares, members, and contacts are stored in your local database, not on our servers
  • No sync issues — Since there's no central server storing your shares/members/contacts, there's nothing to get out of sync
  • Rebuild anytime — Recreate shares, re-add members, re-add contacts — your collaborators' data is on their machines, so they can still discover your shares once you rebuild

Total privacy: Our server only verifies your email during registration. All your shares, members, and contacts are stored locally on your device — we never see them.

Getting Help

Contact Support

Email: support@handrive.app

When contacting support, include:

  • Operating system and version
  • Handrive version (Settings > About)
  • Steps to reproduce the issue
  • Error messages (screenshots or text)
  • Relevant log files

Visit our Support page for FAQs and more information.

See Also