# MinIO

> Connect self-hosted MinIO or MinIO-compatible storage to BucketMate

Canonical: https://docs.bucketmate.app/macos/providers/connect-minio

BucketMate connects to MinIO through its S3-compatible endpoint. MinIO is often self-hosted, so endpoint and TLS setup matter more than with managed providers.

## Prerequisites

- HTTPS MinIO endpoint URL
- Access key
- Secret key
- Bucket name, or permission to list buckets

## Endpoint and region

Use your MinIO endpoint:

```text
https://<your-minio-endpoint>
```

BucketMate defaults MinIO region to:

```text
us-east-1
```

If your MinIO deployment uses another region, choose **Custom** and enter it.

## Connection steps

1. Open BucketMate.
2. Choose **Add Connection**.
3. Select **MinIO**.
4. Enter the HTTPS endpoint.
5. Enter the access key and secret key.
6. Keep region as `us-east-1`, or enter your custom MinIO region.
7. If the credentials cannot list buckets, turn off bucket listing and enter bucket names manually.
8. Use **Test Connection**.
9. Save the connection.

## Common issues and fixes

### Path-style vs virtual-hosted style

MinIO defaults to path-style requests. Fix by using path-style URLs, or configure `MINIO_DOMAIN` to enable virtual-hosted-style access.

### Bucket subdomain conflicts

When `MINIO_DOMAIN` is enabled, subdomains are treated as bucket names. Fix by ensuring DNS records and bucket names do not conflict with other subdomains.

### Cannot connect to localhost

Some setups fail to connect to MinIO on localhost over HTTP. Fix by using HTTPS on localhost and following the step by step guide: [MinIO HTTPS on localhost](/blogs/minio-https-localhost-macos/).

### Browser trust errors

If MinIO uses a self-signed certificate, make sure macOS trusts the certificate before connecting from BucketMate.

### Bucket list permission is restricted

If your MinIO policy allows object access but not bucket listing, turn off **Credentials have permission to list buckets** and enter the bucket names manually.

## BucketMate tips

- Use HTTPS even for local MinIO development.
- Use manual bucket names for restricted MinIO policies.
- Use workspaces to separate local MinIO, staging MinIO, and production storage.