Troubleshooting
Common issues
Plain answers to the questions we hear most. If yours isn't here, the support email at the bottom is monitored by humans.
The list below covers the issues most people hit during their first few weeks with Tusk. If your situation isn't in here, the diagnostic order is usually:
- Check the Jobs page for what's actively running.
- Check the Notifications panel for errors.
- From the macOS menu bar, choose Help → Open Logs to see what Tusk thinks happened.
- Email support@tusk.so with the log file attached.
I picked a folder in the project picker but Tusk says it's empty
Tusk doesn't have macOS permission to read that folder. Open System Settings > Privacy & Security > Files and Folders, find Tusk in the list, and toggle access on for the right category (Documents, Downloads, Desktop, Pictures, Movies, or Removable Volumes for SD cards and external drives). Restart Tusk so the permission change takes effect. Full details on the macOS permissions page.
My external drive keeps showing as disconnected even though it's plugged in
Try a different USB-C / Thunderbolt cable, then a different port on your Mac. Most 'flaky drive' reports turn out to be flaky cables. If the drive shows in Finder but not in Tusk, restart Tusk. If it shows in neither, the issue is upstream of Tusk (cable, hub, port, or the drive itself).
An offload errored on a few files. What do I do?
Open the offload session summary. It lists exactly which files failed and why (read error, checksum mismatch, network timeout). Click Retry to re-attempt those specific files. If the same files keep failing, the source is likely flaky (re-read the card, try a different card reader, or confirm the file isn't corrupted at the source).
Tusk says my Google Drive credentials expired, but I never changed them
Google rotates OAuth tokens periodically. The rotation usually happens transparently, but it can fail if your Google account password changed, you revoked Tusk's access, or Google decided to require a fresh sign-in. Open Preferences > Accounts, click the affected Google Drive entry, and reconnect. The connection picks up where it left off.
An S3 connection test fails but my keys are correct
Most common causes: the endpoint URL has a typo (especially missing or extra subdomain), the region in the endpoint doesn't match the bucket's region, or the credential's policy doesn't include s3:ListBucket (Tusk uses this in the connection check). Double-check each. For self-hosted MinIO, also confirm the TLS certificate is trusted by your Mac.
Tusk crashed mid-offload. Did I lose my files?
No. Offload sessions are persisted to disk; they survive crashes, quits, and restarts. Relaunch Tusk and the session resumes from where it stopped, picking up after the last fully-completed file. The card hasn't been touched, the destinations have whatever was already verified.
I bulk-deleted local files. Where did they go?
The macOS Trash. They're recoverable until you empty the Trash. After that, restore from your backups using the Restore action on the file's row in Tusk. The backup copies on your destinations were not touched by the bulk delete; they're still where Tusk recorded them.
Why does the file table show files I don't have on my Mac?
Those rows are tracked files that don't currently have a local copy. Either you deleted local copies after backing up (the file shows Not local), or you offloaded directly from a card without copying locally (the file shows Remote only). The verified backups are still safe; use Restore on the row to bring the file back.
Tusk's window disappeared but the menu bar icon is still there
That's normal. Closing the window doesn't quit Tusk; it keeps running in the background to handle syncs and offloads. Click the menu bar icon to reopen the window. Right-click the menu bar icon and choose Quit if you want to actually stop the app.
The license activation server is unreachable
Check your internet connection first. If you're online, try again in a few minutes. Tusk caches a signed grace token for several days, so even when the server is briefly unreachable, the app keeps working. If you're past your grace period and the server is still unreachable, contact support and we'll get you a manual activation token.
I renamed my project's primary folder in Finder. Now Tusk shows 'Folder missing'
Click the Relink folder banner in the project header. The picker opens; navigate to the renamed folder and select it. Tusk re-attaches to the new path and your file index, destinations, and history all stay intact. The relink is one-click.
I see Missing badges on a destination after reconnecting a drive
Tusk's reconnect verification found that some files it expected on the drive aren't there anymore. The most common cause is a flaky cable or port giving you a partial mount; replug and run a re-check. If files really are gone (drive failure, third-party tool deleted them), use Redistribute on the affected files to push verified copies back from your other destinations.
The Jobs page is full of queued jobs and nothing is running
A destination is offline or paused. Open the Jobs page, click into a queued job, and check the reason listed. The most common case is a drive that needs to be plugged in or a cloud destination with expired credentials. Fix the underlying issue and the queue starts moving.
An offload preflight says my Google Drive doesn't have enough storage
Tusk checks Google Drive quota before starting an offload to prevent mid-run failures. The error message shows the exact gap. Either upgrade your Google storage, free space in the Drive, pick a different destination for this offload, or remove the Google Drive destination from this project temporarily.
How do I move my Tusk database to a different Mac?
Quit Tusk on the source Mac. Copy ~/Library/Application Support/Tusk/ to the same path on the new Mac. Reactivate your license on the new Mac (a license key allows two activations; if you've used both, ask us to reset). Reconnect any cloud accounts under Preferences > Accounts since OAuth tokens are bound to the macOS Keychain and don't migrate.
Logs are the fastest path to a fix
Related