\n * By default the bucket is initialized with 0 replicas since only a single container is launched. Modifying\n * this value can still be useful in some test scenarios (i.e. to test failures with the wrong number of replicas\n * and durability requirements on operations).\n *
\n * Couchbase buckets can have a maximum of three replicas configured.\n *\n * @param numReplicas the number of replicas to configure.\n * @return this {@link BucketDefinition} for chaining purposes.\n */\n public BucketDefinition withReplicas(final int numReplicas) {\n if (numReplicas < 0 || numReplicas > 3) {\n throw new IllegalArgumentException(\"The number of replicas must be between 0 and 3 (inclusive)\");\n }\n this.numReplicas = numReplicas;\n return this;\n }\n\n /**\n * Enables flush for this bucket (disabled by default).\n *\n * @param flushEnabled if true, the bucket can be flushed.\n * @return this {@link BucketDefinition} for chaining purposes.\n */\n public BucketDefinition withFlushEnabled(final boolean flushEnabled) {\n this.flushEnabled = flushEnabled;\n return this;\n }\n\n /**\n * Sets a custom bucket quota (100MiB by default).","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/couchbase/src/main/java/org/testcontainers/couchbase/BucketDefinition.java#L34-L70","documentation":"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.","triggerScenarios":"Calling bucketDefinition.withReplicas(n) with n < 0 or n > 3, e.g. withReplicas(4) or withReplicas(-1).","commonSituations":"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.","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."],"exampleFix":"// before\nnew BucketDefinition(\"mybucket\").withReplicas(4)\n// after\nnew BucketDefinition(\"mybucket\").withReplicas(1)","handlingStrategy":"validation","validationCode":"if (replicas < 0 || replicas > 3) {\n throw new IllegalArgumentException(\"replicas must be 0..3\");\n}\nbucket.withReplicas(replicas);","typeGuard":null,"tryCatchPattern":"try {\n bucket.withReplicas(n);\n} catch (IllegalArgumentException e) {\n bucket.withReplicas(1); // safe default\n}","preventionTips":["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."],"tags":["testcontainers","couchbase","validation","argument"],"backgroundTag":"value-out-of-range","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}