jwtk/jjwt · error · java.lang.IllegalArgumentException

Start index is less than zero

Error message

Start index is less than zero: ${start}

What it means

Constructor guard of CharSequenceReader(subSequence, start, end): thrown when the requested start index is negative. The reader tolerates indexes beyond the sequence's bounds (it treats them as EOF as the sequence changes), but a negative start is nonsensical and rejected up front as a caller programming error.

Solutions

1. Compute start from a non-negative source (e.g. clamp with Math.max(0, startIndex)) before constructing the reader
2. Fix the offset calculation that produced the negative index (often an off-by-one or an unguarded subtraction)

When it happens

Trigger: Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/CharSequenceReader.java:115 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/12a634c453018df7. Report an issue: GitHub.

Appendix: source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/CharSequenceReader.java:115

     * Constructs a new instance with a portion of the specified character sequence.
     * <p>
     * The start and end indexes are not strictly enforced to be within the bounds
     * of the character sequence. This allows the character sequence to grow or shrink
     * in size without risking any {@link IndexOutOfBoundsException} to be thrown.
     * Instead, if the character sequence grows smaller than the start index, this
     * instance will act as if all characters have been read; if the character sequence
     * grows smaller than the end, this instance will use the actual character sequence
     * length.
     * </p>
     *
     * @param charSequence The character sequence, may be {@code null}
     * @param start        The start index in the character sequence, inclusive
     * @param end          The end index in the character sequence, exclusive
     * @throws IllegalArgumentException if the start index is negative, or if the end index is smaller than the start index
     */
    public CharSequenceReader(final CharSequence charSequence, final int start, final int end) {
        if (start < 0) {
            throw new IllegalArgumentException("Start index is less than zero: " + start);
        }
        if (end < start) {
            throw new IllegalArgumentException("End index is less than start " + start + ": " + end);
        }
        // Don't check the start and end indexes against the CharSequence,
        // to let it grow and shrink without breaking existing behavior.

        this.charSequence = charSequence != null ? charSequence : "";
        this.start = start;
        this.end = end;

        this.idx = start;
        this.mark = start;
    }

    /**
     * Close resets the file back to the start and removes any marked position.
     */

View on GitHub (pinned to fb71496164)