apache/cassandra · error · IllegalStateException

Step %s is invalid for sequence %s

Error message

Step %s is invalid for sequence %s 

What it means

BootstrapAndReplace.nextToIndex maps the replace sequence's Transformation.Kind (START_REPLACE=0, MID_REPLACE=1, FINISH_REPLACE=2) to an ordinal index. IllegalStateException is thrown for kinds outside the replace sequence, which cannot occur in a well-formed BootstrapAndReplace.

Source

Thrown at src/java/org/apache/cassandra/tcm/sequences/BootstrapAndReplace.java:385

                                        .forEach(source -> movements.put(destination, source));
            });
            movementMapBuilder.put(params, movements.build());
        });
        return movementMapBuilder.build();
    }

    private static int nextToIndex(Transformation.Kind next)
    {
        switch (next)
        {
            case START_REPLACE:
                return 0;
            case MID_REPLACE:
                return 1;
            case FINISH_REPLACE:
                return 2;
            default:
                throw new IllegalStateException(String.format("Step %s is invalid for sequence %s ", next, REPLACE));
        }
    }

    private static Transformation.Kind indexToNext(int index)
    {
        switch (index)
        {
            case 0:
                return START_REPLACE;
            case 1:
                return MID_REPLACE;
            case 2:
                return FINISH_REPLACE;
            default:
                throw new IllegalStateException(String.format("Step %s is invalid for sequence %s ", index, REPLACE));
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Validate the stored Transformation.Kind belongs to the replace family before constructing the sequence
2. Re-fetch/replay cluster metadata to obtain a consistent transformation state
3. Check construction sites so BootstrapAndReplace only receives START_REPLACE/MID_REPLACE/FINISH_REPLACE
4. Upgrade all nodes consistently if version skew over transformation kinds is suspected

Example fix

// before
BootstrapAndReplace seq = new BootstrapAndReplace(replacement, next, ...);
// after
if (next != Transformation.Kind.START_REPLACE && next != MID_REPLACE && next != FINISH_REPLACE)
    throw new IllegalArgumentException("kind not part of BootstrapAndReplace: " + next);
BootstrapAndReplace seq = new BootstrapAndReplace(replacement, next, ...);

Set<Transformation.Kind> replaceKinds = Set.of(START_REPLACE, MID_REPLACE, FINISH_REPLACE);
if (!replaceKinds.contains(kind)) throw new IllegalArgumentException("not a replace kind: " + kind);

try { BootstrapAndReplace seq = reconstruct(state); } catch (IllegalStateException e) { /* re-read metadata / repair transformation log */ }

When it happens

Trigger: Constructing or advancing a BootstrapAndReplace whose current step is a JOIN-family kind or other non-replace Transformation.Kind, typically from malformed metadata or a wrong-argument construction.

Common situations: Transformation log corruption/replay assigns a join kind to a replace sequence; a developer passes the wrong kind into the BootstrapAndReplace constructor; version skew between nodes interpreting transformation kinds differently.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Step %s is invalid for sequence %s
• Can't revert replacement from
• Can't revert join from
• Can only initialize cluster identifier during epoch %d, but
• Tried to commit when in gossip mode

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/cbee338b526e4afe. Report an issue: GitHub.