Troubleshooting
Diagnose connection errors, read connection diagnostics, and fix common BucketMate for macOS problems
Use this page when a connection fails, buckets do not load, or data in BucketMate looks out of date.
Connection issue warning
When BucketMate cannot load buckets for a connection, it shows an orange warning icon next to the connection in the sidebar.
- Click the warning icon.
- Read the problem and the suggested fix.
- Choose Retry, Edit connection, or View details.
| Problem | What to check |
|---|---|
| Invalid credentials | Check the access key and secret key. If you use a temporary token, make sure it is still valid. |
| Cannot list buckets | Check that the credentials can list buckets. If not, turn off Load all buckets and enter bucket names manually. |
| Signature mismatch | Check the secret key, region, and endpoint. For Google Cloud Storage, use HMAC keys. |
| Session expired | Log in again, then retry. |
| Endpoint unreachable | Check the endpoint URL, your network, and any VPN or proxy. |
| Secure connection failed | Check that the endpoint has a valid TLS certificate. For local MinIO, use the correct http:// or https:// endpoint. |
| Bucket not found | Check the bucket name and make sure the credentials can access it. |
| Rate limited | Wait a moment, then retry. |
| Service unavailable | Retry later or check the provider status page. |
Connection diagnostics
BucketMate records each connection attempt with its steps, requests, and errors.
Open diagnostics in one of these ways:
- Choose View logs in the connection form.
- Choose View details in the connection issue popover.
In Connection diagnostics you can:
- Search attempts and filter them by status.
- Select an attempt to see each request, the HTTP status, the request ID, and the raw error.
- Choose Copy diagnostics or Export for one attempt.
- Choose Export all to save every attempt.
- Choose Clear all to remove all diagnostics.
Exported diagnostics include request and response headers. Review them before you share them with support.
AWS SSO session expired
When an AWS SSO session expires, BucketMate shows SSO session expired.
- Choose Log in again.
- Finish signing in in your browser.
- Return to BucketMate.
The AWS CLI must be installed for SSO login.
Buckets do not load
- If the credentials cannot list all buckets, edit the connection, turn off Load all buckets, and enter bucket names manually.
- Check that the endpoint and region match the provider. See the provider guides for endpoint formats.
- Right-click the connection and choose Refresh.
Files look out of date
BucketMate caches bucket and object lists to make browsing faster.
- Press Command-R, or choose Refresh in the toolbar.
- If data still looks stale, open Settings > Advanced and choose Clear All Cache.
Search does not find files in a large bucket
Large buckets must be indexed before search works. Choose Load all items when BucketMate shows Large bucket detected, and wait for indexing to finish.
Preview or open fails for an archived file
Files in archive storage classes, such as AWS Glacier Flexible or Deep Archive, must be restored first. See Storage classes.
Temporary files use too much disk space
Open Settings > Advanced, then choose Empty Directory under Temporary data. Turn on Auto-clear temporary data on app exit to clean up automatically.
Reset BucketMate
As a last resort, open Settings > Advanced and choose Clear All Data. This removes all settings, connections, and cache, then quits BucketMate. This cannot be undone.
Get help
- Choose Help > Report Bug... to report a bug.
- Choose Help > Send Feedback... to share feedback.
- Open Settings > About for links to email support, the Discord community, and release notes.