apache/cassandra · error · ConfigurationException

Tokens may not contain the character " +…

Error message

Tokens may not contain the character " + VersionedValue.DELIMITER_STR

What it means

OrderPreservingPartitioner tokens are UTF-8 strings, and Gossip's VersionedValue uses '|' as a delimiter inside gossip state. A token string containing the delimiter would corrupt gossip encoding, so TokenFactory.validate rejects any token containing VersionedValue.DELIMITER_STR ('|') with a ConfigurationException.

Solutions

1. Remove or replace the '|' character in the token string before assigning it as initial_token.
2. Add pre-validation in your token-generation script: reject tokens containing '|'.
3. Prefer switching to Murmur3Partitioner — OrderPreservingPartitioner is legacy and string tokens have this and other restrictions.
4. If calling validate() in code, catch ConfigurationException and re-prompt/re-derive the token.

Example fix

// before
String token = "abc|def"; // contains gossip delimiter
factory.validate(token); // throws
// after
String token = rawToken.replace("|", "");
if (!token.contains(VersionedValue.DELIMITER_STR)) factory.validate(token);

public static boolean isValidOppToken(String token) {
    return token != null && !token.isEmpty() && !token.contains(VersionedValue.DELIMITER_STR);
}

boolean gossipSafeToken(String t) { return !t.contains("|"); }

try {
    factory.validate(token);
} catch (ConfigurationException e) {
    throw new IllegalArgumentException("Token must not contain the gossip delimiter '|' ", e);
}

When it happens

Trigger: Calling OrderPreservingPartitioner.getTokenFactory().validate(token) (e.g. when loading initial_token from cassandra.yaml or validating user input) with a token containing the '|' character.

Common situations: initial_token in cassandra.yaml containing a pipe (paths, regexes, or UUID-like strings with separators pasted as tokens); scripting token generation on a legacy OPP cluster without filtering the delimiter.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Can't delete hints for unknown address
• Invalid Token:
• Token must be >= 0 and <= 2**127
• Token " + token + " contains non-hex digits
• A CounterId representation is exactly

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

Appendix: source

Thrown at src/java/org/apache/cassandra/dht/OrderPreservingPartitioner.java:201

            {
                return new StringToken(ByteBufferUtil.string(bytes));
            }
            catch (CharacterCodingException e)
            {
                throw new RuntimeException(e);
            }
        }

        public String toString(Token token)
        {
            StringToken stringToken = (StringToken) token;
            return stringToken.token;
        }

        public void validate(String token) throws ConfigurationException
        {
            if (token.contains(VersionedValue.DELIMITER_STR))
                throw new ConfigurationException("Tokens may not contain the character " + VersionedValue.DELIMITER_STR);
        }

        public Token fromString(String string)
        {
            return new StringToken(string);
        }
    };

    public Token.TokenFactory getTokenFactory()
    {
        return tokenFactory;
    }

    public boolean preservesOrder()
    {
        return true;
    }

View on GitHub (pinned to 88fd0f6a0e)