testcontainers/testcontainers-java · error · IllegalArgumentException

The custom quota (quotaMb) must not be smaller than the…

Error message

The custom quota (quotaMb) must not be smaller than the minimum quota for the service (service.getMinimumQuotaMb())

What it means

CouchbaseContainer.withServiceQuota throws IllegalArgumentException when quotaMb is smaller than the service's minimum memory quota (service.getMinimumQuotaMb()). Each Couchbase service has its own server-enforced minimum; Testcontainers validates it eagerly before container start.

Solutions

Raise quotaMb to at least service.getMinimumQuotaMb(), e.g. container.withServiceQuota(CouchbaseService.KV, Math.max(quotaMb, service.getMinimumQuotaMb())).
Check CouchbaseService.getMinimumQuotaMb() for the specific service's floor before calling.
If the host is memory-constrained, enable fewer services instead of lowering quotas.

Example fix

// before
container.withServiceQuota(CouchbaseService.KV, 100)
// after
int quota = Math.max(100, CouchbaseService.KV.getMinimumQuotaMb());
container.withServiceQuota(CouchbaseService.KV, quota)

Defensive patterns

Strategy: validation

Validate before calling

int quota = Math.max(quotaMb, service.getMinimumQuotaMb());
container.withServiceQuota(service, quota);

Try / catch

try {
    container.withServiceQuota(service, quotaMb);
} catch (IllegalArgumentException e) {
    container.withServiceQuota(service, service.getMinimumQuotaMb());
}

Prevention

Always derive quota from service.getMinimumQuotaMb() rather than hardcoding.
Don't assume the 100MB bucket minimum applies to service quotas.
Budget host memory against the sum of service minimums.

When it happens

Trigger: Calling e.g. container.withServiceQuota(CouchbaseService.KV, 100) when the KV service minimum is 256 MB.

Common situations: Applying a bucket-level 100MB minimum to service quotas; copying one service's quota to another with a higher minimum; memory-saving attempts below server limits.

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

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

Appendix: source

Thrown at modules/couchbase/src/main/java/org/testcontainers/couchbase/CouchbaseContainer.java:183

        checkNotRunning();
        this.enabledServices = EnumSet.copyOf(Arrays.asList(enabled));
        return this;
    }

    /**
     * Configures a custom memory quota for a given service.
     *
     * @param service the service to configure the quota for.
     * @param quotaMb the memory quota in MB.
     * @return this {@link CouchbaseContainer} for chaining purposes.
     */
    public CouchbaseContainer withServiceQuota(final CouchbaseService service, final int quotaMb) {
        checkNotRunning();
        if (!service.hasQuota()) {
            throw new IllegalArgumentException("The provided service (" + service + ") has no quota to configure");
        }
        if (quotaMb < service.getMinimumQuotaMb()) {
            throw new IllegalArgumentException(
                "The custom quota (" +
                quotaMb +
                ") must not be smaller than the " +
                "minimum quota for the service (" +
                service.getMinimumQuotaMb() +
                ")"
            );
        }
        this.customServiceQuotas.put(service, quotaMb);
        return this;
    }

    /**
     * Enables the analytics service which is not enabled by default.
     *
     * @return this {@link CouchbaseContainer} for chaining purposes.
     */
    public CouchbaseContainer withAnalyticsService() {

View on GitHub (pinned to 8e549514e3)