testcontainers/testcontainers-java · error · IllegalArgumentException

Bucket quota cannot be less than 100MB!

Error message

Bucket quota cannot be less than 100MB!

What it means

BucketDefinition.withQuota rejects quota values below 100 MiB with an IllegalArgumentException. Couchbase enforces a 100MB minimum memory quota per bucket, so a smaller value would fail server-side; Testcontainers fails fast instead. The unit is mebibytes.

Solutions

1. Pass a quota of at least 100 (MiB).
2. If memory-constrained, create fewer buckets each at 100 MiB rather than shrinking below the minimum.
3. Note Couchbase Server's cluster-level minimum bucket quota may be higher on some versions; use >= 100 and increase if the server rejects it.

Example fix

// before
new BucketDefinition("mybucket").withQuota(50)
// after
new BucketDefinition("mybucket").withQuota(100)

if (quotaMb < 100) {
    throw new IllegalArgumentException("quota must be >= 100 MiB");
}
bucket.withQuota(quotaMb);

try {
    bucket.withQuota(q);
} catch (IllegalArgumentException e) {
    bucket.withQuota(100);
}

When it happens

Trigger: Calling bucketDefinition.withQuota(q) with q < 100, e.g. withQuota(50).

Common situations: Setting a small quota to save memory on a dev machine; mixing up MB and GB units; assuming the same minimum as another database.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• The custom quota (quotaMb) must not be smaller than the…
• The number of replicas must be between 0 and 3 (inclusive)
• The provided service (service) has no quota to configure
• Couchbase /pools did not return valid JSON
• The Analytics Service is only supported with the Enterprise…

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/8218d58764af8d8f. Report an issue: GitHub.

Appendix: source

Thrown at modules/couchbase/src/main/java/org/testcontainers/couchbase/BucketDefinition.java:77

     * Enables flush for this bucket (disabled by default).
     *
     * @param flushEnabled if true, the bucket can be flushed.
     * @return this {@link BucketDefinition} for chaining purposes.
     */
    public BucketDefinition withFlushEnabled(final boolean flushEnabled) {
        this.flushEnabled = flushEnabled;
        return this;
    }

    /**
     * Sets a custom bucket quota (100MiB by default).
     *
     * @param quota the quota to set for the bucket in mebibytes.
     * @return this {@link BucketDefinition} for chaining purposes.
     */
    public BucketDefinition withQuota(final int quota) {
        if (quota < 100) {
            throw new IllegalArgumentException("Bucket quota cannot be less than 100MB!");
        }
        this.quota = quota;
        return this;
    }

    /**
     * Allows to disable creating a primary index for this bucket (enabled by default).
     *
     * @param create if false, a primary index will not be created.
     * @return this {@link BucketDefinition} for chaining purposes.
     */
    public BucketDefinition withPrimaryIndex(final boolean create) {
        this.queryPrimaryIndex = create;
        return this;
    }

    public String getName() {
        return name;

View on GitHub (pinned to 8e549514e3)