pinpoint-apm/pinpoint · error · IllegalArgumentException

${sequenceLimit} > MAX_SEQUENCE

Error message

${sequenceLimit} > MAX_SEQUENCE

What it means

SequenceSpanEventFilter limits filtering to span events whose sequence is below MAX_SEQUENCE (the maximum representable span-event sequence). A sequenceLimit greater than MAX_SEQUENCE can never be honored, so the constructor rejects it eagerly with this IllegalArgumentException.

Source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/filter/SequenceSpanEventFilter.java:42

/**
 * @author Woonduk Kang(emeroad)
 */
public class SequenceSpanEventFilter implements SpanEventFilter {

    private final Logger logger = LogManager.getLogger(this.getClass());

    public static final int MAX_SEQUENCE = Short.MAX_VALUE;
    public static final int DEFAULT_SEQUENCE_LIMIT = 1024*10;

    private final int sequenceLimit;

    public SequenceSpanEventFilter() {
        this(DEFAULT_SEQUENCE_LIMIT);
    }

    public SequenceSpanEventFilter(int sequenceLimit) {
        if (sequenceLimit > MAX_SEQUENCE) {
            throw new IllegalArgumentException(sequenceLimit + " > MAX_SEQUENCE");
        }
        this.sequenceLimit = sequenceLimit;
    }

    @Override
    public boolean filter(SpanEventBo spanEventBo) {
        if (spanEventBo == null) {
            return REJECT;
        }
        final int sequence = spanEventBo.getSequence();
        if (sequence < 0 || sequence > sequenceLimit) {
            if (logger.isTraceEnabled()) {
                logger.trace("discard spanEvent:{}", spanEventBo);
            }
            return REJECT;
        }
        return ACCEPT;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Lower the configured sequenceLimit to at most MAX_SEQUENCE
2. Clamp the parsed config value with Math.min(value, MAX_SEQUENCE) before constructing the filter
3. Remove the custom override and use the default constructor (DEFAULT_SEQUENCE_LIMIT)

Example fix

// before
new SequenceSpanEventFilter(config.getSequenceLimit()); // may exceed MAX_SEQUENCE
// after
int limit = Math.min(config.getSequenceLimit(), SequenceSpanEventFilter.MAX_SEQUENCE);
new SequenceSpanEventFilter(limit);

int limit = Math.min(configuredLimit, SequenceSpanEventFilter.MAX_SEQUENCE);
SpanEventFilter filter = new SequenceSpanEventFilter(limit);

boolean isValidSequenceLimit(int limit) {
    return limit <= SequenceSpanEventFilter.MAX_SEQUENCE;
}

try {
    filter = new SequenceSpanEventFilter(configuredLimit);
} catch (IllegalArgumentException e) {
    logger.warn("sequenceLimit too high, using default", e);
    filter = new SequenceSpanEventFilter();
}

When it happens

Trigger: Instantiating SequenceSpanEventFilter (or the no-arg variant if DEFAULT_SEQUENCE_LIMIT were ever misconfigured) with a sequenceLimit exceeding MAX_SEQUENCE — e.g. from config that reads a user-supplied limit without clamping.

Common situations: Setting an unbounded custom span event filter limit in collector/Web configuration; misreading the constant as millis or another unit; copy-pasted tuning values from documentation for a different version.

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

• negative cache size:${size}
• Invalid value:<value>
• Unknown AgentType:
• Failed to detect pinpoint profile. Please add -Dpinpoint.act
• unsupported profile or profile alias:

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/587feaf1d439690c. Report an issue: GitHub.