apache/cassandra · error · ConfigurationException

property was set to seconds which is not in allowed range…

Error message

property %s was set to %s seconds which is not in allowed range of [%s..%s]

What it means

When using the IMDSv2 connector, the token TTL property (ec2_metadata_token_ttl_seconds) must fall within the allowed range [MIN_TOKEN_TIME_IN_SECONDS..MAX_TOKEN_TIME_IN_SECONDS]. Values outside the range throw ConfigurationException at connector creation time.

Solutions

1. Set ec2_metadata_token_ttl_seconds to a value between 1 and 21600 (e.g. 21600 for the maximum)
2. Remove the property to use the default TTL
3. If a longer effective session is needed, keep the max TTL — the connector refreshes tokens as required
4. Fix unit confusion: the property is in seconds, not ms or hours

Example fix

// before (cassandra.yaml)
ec2_metadata_token_ttl_seconds: 86400
// after
ec2_metadata_token_ttl_seconds: 21600

long ttl = Long.parseLong(props.get("ec2_metadata_token_ttl_seconds", "21600"));
if (ttl < 1 || ttl > 21600) throw new IllegalArgumentException("TTL must be in [1..21600] seconds");

try { Ec2MetadataServiceConnector.create(props); }
catch (ConfigurationException e) { logger.error("Bad ec2_metadata_token_ttl_seconds: {}", e.getMessage()); }

When it happens

Trigger: create() parses ec2_metadata_token_ttl_seconds via Integer.parseInt, and the resulting Duration in seconds is < MIN_TOKEN_TIME_IN_SECONDS or > MAX_TOKEN_TIME_IN_SECONDS (IMDS allows 1–21600 seconds).

Common situations: Operator sets a TTL of 0 or 60 thinking it's a refresh hint; copy-paste of a value like 86400 (a day) exceeding the 6-hour IMDSv2 max; confusion between milliseconds and seconds.

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

• must be one of
• Unable to parse integer from property
• Must permit at least one attempt
• Request on table . with %sttl of seconds exceeds maximum…
• retries must be non-negative

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

Appendix: source

Thrown at src/java/org/apache/cassandra/locator/Ec2MetadataServiceConnector.java:130

        static int HTTP_REQUEST_RETRIES = 1;

        private Pair<String, Long> token;
        @VisibleForTesting
        final Duration tokenTTL;

        static V2Connector create(SnitchProperties props)
        {
            String tokenTTLString = props.get(AWS_EC2_METADATA_TOKEN_TTL_SECONDS_HEADER_PROPERTY,
                                              Integer.toString(MAX_TOKEN_TIME_IN_SECONDS));

            Duration tokenTTL;
            try
            {
                tokenTTL = Duration.ofSeconds(Integer.parseInt(tokenTTLString));

                if (tokenTTL.getSeconds() < MIN_TOKEN_TIME_IN_SECONDS || tokenTTL.getSeconds() > MAX_TOKEN_TIME_IN_SECONDS)
                {
                    throw new ConfigurationException(format("property %s was set to %s seconds which is not in allowed range of [%s..%s]",
                                                            AWS_EC2_METADATA_TOKEN_TTL_SECONDS_HEADER_PROPERTY,
                                                            tokenTTL.getSeconds(),
                                                            MIN_TOKEN_TIME_IN_SECONDS,
                                                            MAX_TOKEN_TIME_IN_SECONDS));
                }
            }
            catch (NumberFormatException ex)
            {
                throw new ConfigurationException(format("Unable to parse integer from property %s, value to parse: %s",
                                                        AWS_EC2_METADATA_TOKEN_TTL_SECONDS_HEADER_PROPERTY, tokenTTLString));
            }

            return new V2Connector(props, tokenTTL);
        }

        V2Connector(SnitchProperties properties, Duration tokenTTL)
        {
            super(properties);

View on GitHub (pinned to 88fd0f6a0e)