Troubleshooting
macOS blocks the app
Section titled “macOS blocks the app”The app is not notarized yet. Follow the first-launch steps in Getting started.
A connection test fails
Section titled “A connection test fails”Check the endpoint, region, bucket, and credentials in Connection settings. Use the service endpoint without the bucket or a folder path. Include the session token when your credentials require one.
Check that your credentials have access to the bucket and that your storage endpoint is reachable.
For encrypted drives, an incorrect password or unencrypted names in the top folder can prevent connection. See Encryption.
A drive needs reconnecting
Section titled “A drive needs reconnecting”Click Reconnect in the app or menu bar. UnlocalFS tries a normal eject, waits for the old service to stop, and connects using the same cache. Recovery stops if the drive cannot eject or the old service cannot stop. Close files open on the drive before trying again.
Wake and network changes refresh drive health. Reconnecting stays manual.
Uploads fail or disconnect is blocked
Section titled “Uploads fail or disconnect is blocked”Select the drive to see pending uploads and retries. UnlocalFS sends a notification when files cannot upload. Restore network access and check that the credentials still allow writes.
The app will not disconnect while uploads are pending or need a retry. If you tried to disconnect, it sends a notification when uploads finish. Do not delete the cache while uploads are pending.
Click Open Log to inspect the drive log. Logs are in ~/Library/Logs/UnlocalFS.
Changes from another app do not appear
Section titled “Changes from another app do not appear”Changes made through another app, drive, or Mac normally appear within 5 minutes. Choose Refresh Files in the app, sidebar menu, or menu bar to see them sooner.
Avoid editing the same file through two drives at once: one save can overwrite the other.
Share link services are missing
Section titled “Share link services are missing”Open UnlocalFS once. Enable the entries in System Settings → Keyboard → Keyboard Shortcuts → Services → Files and Folders. Links require a connected, unencrypted drive and an uploaded file.
Finder adds .DS_Store files
Section titled “Finder adds .DS_Store files”To stop Finder from writing .DS_Store files on network drives, run:
defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool truekillall FinderThis setting applies to all network drives. macOS can still add ._ files when copying files with extended attributes.