# Troubleshooting

> Diagnose connection errors, read connection diagnostics, and fix common BucketMate for macOS problems

Canonical: https://docs.bucketmate.app/macos/advance/troubleshooting

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.

1. Click the warning icon.
2. Read the problem and the suggested fix.
3. 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**.

1. Choose **Log in again**.
2. Finish signing in in your browser.
3. 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.

1. Press Command-R, or choose **Refresh** in the toolbar.
2. 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](/macos/features/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.