How to Create MinIO Buckets in Spring Boot

June 05, 2025

#1

When working with MinIO in a Spring Boot application, one of the first things you’ll need to do is create buckets. Buckets are like folders where your application can upload, store, and retrieve files—similar to AWS S3.
In this article, we'll walk you through how to create MinIO buckets in Spring Boot using the official MinIO Java SDK. This guide assumes you’ve already connected Spring Boot to your MinIO server. If not, make sure you have your MinIO configuration set up first.
Let’s get started!

What Is a Bucket in MinIO?

A bucket is a logical container where you store your objects (files). Every object in MinIO must exist inside a bucket. So before uploading anything—images, PDFs, documents, or logs—you need to make sure the appropriate bucket exists.

Prerequisites

To follow along, make sure:

• You have a working Spring Boot project.
• You’ve added the MinIO Java SDK as a dependency.
• Your application is already configured to connect to a MinIO server (using application.properties or application.yml).

If you're not set up yet, check out:
👉 [Spring Boot MinIO Project Setup Guide]
👉 [Connect Spring Boot to MinIO Server]

Add the MinIO SDK Dependency

First, make sure you’ve added the MinIO SDK to your pom.xml if you're using Maven:

<dependency>
  <groupid>io.minio</groupid>
  <artifactid>minio</artifactid>
  <version>8.5.7</version> <!--or latest-->

For Gradle:

implementation 'io.minio:minio:8.5.7'

Step 1: Create a MinIO Client Bean

In your Spring Boot application, define a MinioClient bean. This is used to interact with the MinIO server.

@Configuration
public class MinioConfig {

    @Value("${minio.url}")
    private String url;

    @Value("${minio.access-key}")
    private String accessKey;

    @Value("${minio.secret-key}")
    private String secretKey;

    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
            .endpoint(url)
            .credentials(accessKey, secretKey)
            .build();
    }
}

Make sure your application.properties or application.yml

Step 2: Create the Bucket Programmatically

Now you’re ready to create a bucket using the MinIO Java SDK. You’ll want to check if the bucket exists first before creating it.

@Service
public class MinioBucketService {

    private final MinioClient minioClient;

    public MinioBucketService(MinioClient minioClient) {
        this.minioClient = minioClient;
    }

    public void createBucket(String bucketName) {
        try {
            boolean found = minioClient.bucketExists(
                BucketExistsArgs.builder().bucket(bucketName).build()
            );

            if (!found) {
                minioClient.makeBucket(
                    MakeBucketArgs.builder().bucket(bucketName).build()
                );
                System.out.println("Bucket '" + bucketName + "' created.");
            } else {
                System.out.println("Bucket '" + bucketName + "' already exists.");
            }
        } catch (Exception e) {
            System.err.println("Error creating bucket: " + e.getMessage());
        }
    }
}

This service checks if the bucket exists and creates it only if it doesn't. This way, you avoid errors and unnecessary operations.

Step 3: Call the Bucket Creation Logic

You can now call the createBucket() method wherever needed—like in a controller, service initializer, or even automatically on application startup.

Option A: Use a Controller Endpoint

@RestController
@RequestMapping("/api/bucket")
public class BucketController {

    private final MinioBucketService bucketService;

    public BucketController(MinioBucketService bucketService) {
        this.bucketService = bucketService;
    }

    @PostMapping("/{name}")
    public ResponseEntity<String> createBucket(@PathVariable String name) {
        bucketService.createBucket(name);
        return ResponseEntity.ok("Bucket creation requested: " + name);
    }
}

Now, you can test it with a simple HTTP POST:

POST http://localhost:8080/api/bucket/my-new-bucket

Extra Tips

• Use lowercase for bucket names. MinIO (like S3) requires DNS-compliant bucket names.
• Handle exceptions properly—e.g., if MinIO is down or credentials are wrong.
• You can also add policies or enable versioning when creating buckets (advanced usage).

Best Practices

• Check before creating: Always check if a bucket exists to avoid duplicates.
• Use environment-specific buckets: For example, dev-uploads, prod-logs, etc.
• Keep bucket names descriptive: Especially if you're handling multiple apps or services.