apache/cassandra · error · IllegalStateException

Step %s is invalid for sequence %s

Error message

Step %s is invalid for sequence %s 

What it means

BootstrapAndJoin.nextToIndex maps the sequence's current Transformation.Kind to its ordinal index (START_JOIN=0, MID_JOIN=1, FINISH_JOIN=2). It throws IllegalStateException for any other kind, since that kind cannot belong to a BootstrapAndJoin sequence.

Source

Thrown at src/java/org/apache/cassandra/tcm/sequences/BootstrapAndJoin.java:477

                });
            }
            movementMapBuilder.put(params, movements.build());
        });
        return movementMapBuilder.build();
    }

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the Transformation.Kind stored in metadata for this node actually belongs to the JOIN sequence family
2. Replay or re-fetch cluster metadata to recover a consistent transformation log
3. If this occurs during deserialization of a plan, check for version skew between nodes running different transformation kinds and upgrade consistently
4. Fix construction sites so BootstrapAndJoin is only created with START_JOIN/MID_JOIN/FINISH_JOIN kinds

Example fix

// before
BootstrapAndJoin seq = new BootstrapAndJoin(nodeId, anyKind, ...);
// after
if (kind != Transformation.Kind.START_JOIN && kind != MID_JOIN && kind != FINISH_JOIN)
    throw new IllegalArgumentException("kind not part of BootstrapAndJoin: " + kind);
BootstrapAndJoin seq = new BootstrapAndJoin(nodeId, kind, ...);

Set<Transformation.Kind> joinKinds = Set.of(START_JOIN, MID_JOIN, FINISH_JOIN);
if (!joinKinds.contains(kind)) throw new IllegalArgumentException("not a join kind: " + kind);

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

When it happens

Trigger: Constructing or advancing a BootstrapAndJoin sequence whose current step (next) is a Transformation.Kind from another sequence type (e.g. REPLACE kinds) or an uninitialized value.

Common situations: Metadata deserialization or replay produced a step kind inconsistent with this sequence class; a coding error constructs BootstrapAndJoin with a REPLACE-state kind; metadata corruption after a partial transform application.

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

• Can't revert join from
• Step %s is invalid for sequence %s
• Expected to complete startup sequence, but did not. Can't pr
• Can't revert replacement from
• Can not resume bootstrap as join sequence has not been start

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