apereo/cas · error · IllegalArgumentException

Invalid unique index: must be >= 0 and < 256

Error message

Invalid unique index: must be >= 0 and < 256

What it means

CasTomcatServletWebServerFactory.ClusterMemberDesc parses cluster member specs of the form address:port:index for Tomcat cluster session replication. It throws IllegalArgumentException when the third field (the unique index used to build the member's uniqueId bytes) is negative or exceeds UNIQUE_ID_LIMIT (255).

Solutions

1. Set each member's unique index to a distinct value in the range 0-255 (e.g. 0, 1, 2 ...).
2. Use the full address:port:index spec format with exactly three colon-separated numeric fields.
3. Assign indexes deterministically per node (e.g. via per-node env config) so no node exceeds 255 in large fleets.

Example fix

// before
-Dcas.webserver.cluster.membership=node1:4000:300
// after
-Dcas.webserver.cluster.membership=node1:4000:3

// validate the membership spec before startup
def spec = 'node1:4000:3'
def parts = spec.split(':', -1)
assert parts.length == 3
assert parts[2].isInteger() && parts[2].toInteger() in 0..255

static boolean isValidMemberSpec(String spec) {
    var parts = spec.split(":", -1);
    if (parts.length != 3) return false;
    try { int i = Integer.parseInt(parts[2]); return i >= 0 && i < 256; }
    catch (NumberFormatException e) { return false; }
}

When it happens

Trigger: A cluster membership property value passed to the embedded Tomcat factory (e.g. -Dcas.webserver.cluster.membership=host1:4000:300) contains an index outside 0-255, or the spec has malformed numeric fields.

Common situations: Typo when configuring Tomcat cluster membership in a multi-node deployment; copying an index from another node without rebasing; hand-editing env vars in Kubernetes/compose files.

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

• Unable to build a MongoDb client without any hosts/servers…
• subordinate directory
• subordinate directory
• No user can be accepted because none is defined
• Not all requested multifactor providers could be found…

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/63d4fc1128085d0f. Report an issue: GitHub.

Appendix: source

Thrown at webapp/cas-server-webapp-init-tomcat/src/main/java/org/apereo/cas/tomcat/CasTomcatServletWebServerFactory.java:228

    @ToString
    private static final class ClusterMemberDesc {
        private static final int UNIQUE_ID_LIMIT = 255;

        private static final int UNIQUE_ID_ITERATIONS = 16;

        private final String address;

        private final int port;

        private String uniqueId;

        ClusterMemberDesc(final String spec) {
            val values = spec.split(":", -1);
            address = values[0];
            port = Integer.parseInt(values[1]);
            var index = Integer.parseInt(values[2]);
            if (index < 0 || index > UNIQUE_ID_LIMIT) {
                throw new IllegalArgumentException("Invalid unique index: must be >= 0 and < 256");
            }
            uniqueId = "{";
            for (var i = 0; i < UNIQUE_ID_ITERATIONS; i++, index++) {
                if (i != 0) {
                    uniqueId += ',';
                }
                uniqueId += index % (UNIQUE_ID_LIMIT + 1);
            }
            uniqueId += '}';
        }
    }
}

View on GitHub (pinned to e7288fc434)