What causes "The number of replicas must be between 0 and 3 (inclusive)" in testcontainers/testcontainers-java?

Pass a value between 0 and 3 inclusive.

testcontainers/testcontainers-java · error · IllegalArgumentException

The number of replicas must be between 0 and 3 (inclusive)

Error message

The number of replicas must be between 0 and 3 (inclusive)

What it means

BucketDefinition.withReplicas validates that the requested replica count is between 0 and 3 inclusive and throws IllegalArgumentException otherwise. Couchbase buckets support at most 3 replicas, and a negative count is meaningless. The value is rejected before being stored on the bucket definition.

Solutions

Pass a value between 0 and 3 inclusive.
If you need more redundancy than 3 replicas, that is a Couchbase server limitation — redesign the bucket topology.
Verify you are not passing a replica index where a replica count is expected.

Example fix

// before
new BucketDefinition("mybucket").withReplicas(4)
// after
new BucketDefinition("mybucket").withReplicas(1)

Defensive patterns

Strategy: validation

Validate before calling

if (replicas < 0 || replicas > 3) {
    throw new IllegalArgumentException("replicas must be 0..3");
}
bucket.withReplicas(replicas);

Try / catch

try {
    bucket.withReplicas(n);
} catch (IllegalArgumentException e) {
    bucket.withReplicas(1); // safe default
}

Prevention

Remember Couchbase max replicas is 3.
Don't confuse replica count with replica index.
Clamp with Math.max(0, Math.min(3, n)) before calling.

When it happens

Trigger: Calling bucketDefinition.withReplicas(n) with n < 0 or n > 3, e.g. withReplicas(4) or withReplicas(-1).

Common situations: Confusing replica count with replica index (valid indexes are 0..numReplicas-1); copy-pasting a couchbase server-side replica setting that exceeds 3; off-by-one errors.

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/1054e99b46713c53. Report an issue: GitHub.

Appendix: source

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

    public BucketDefinition(final String name) {
        this.name = name;
    }

    /**
     * Allows to configure the number of replicas on a bucket (defaults to 0).
     * <p>
     * By default the bucket is initialized with 0 replicas since only a single container is launched. Modifying
     * this value can still be useful in some test scenarios (i.e. to test failures with the wrong number of replicas
     * and durability requirements on operations).
     * <p>
     * Couchbase buckets can have a maximum of three replicas configured.
     *
     * @param numReplicas the number of replicas to configure.
     * @return this {@link BucketDefinition} for chaining purposes.
     */
    public BucketDefinition withReplicas(final int numReplicas) {
        if (numReplicas < 0 || numReplicas > 3) {
            throw new IllegalArgumentException("The number of replicas must be between 0 and 3 (inclusive)");
        }
        this.numReplicas = numReplicas;
        return this;
    }

    /**
     * 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).

View on GitHub (pinned to 8e549514e3)