apache/rocketmq · error · RuntimeException

Invalid ConsumeFromWhere Value

Error message

Invalid ConsumeFromWhere Value

What it means

DefaultLitePullConsumer.setConsumeFromWhere only accepts CONSUME_FROM_FIRST_OFFSET, CONSUME_FROM_LAST_OFFSET, or CONSUME_FROM_TIMESTAMP; any other value (including null or a locally-added enum constant) throws a bare RuntimeException. Note this lite consumer does NOT support CONSUME_FROM_FIRST_OFFSET semantics for brand-new groups the same way the push consumer does, but the setter's whitelist is the three listed constants. It is a fail-fast guard against unsupported start positions.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/consumer/DefaultLitePullConsumer.java:579

    }

    public void setTopicMetadataCheckIntervalMillis(long topicMetadataCheckIntervalMillis) {
        this.topicMetadataCheckIntervalMillis = topicMetadataCheckIntervalMillis;
    }

    public void setConsumerGroup(String consumerGroup) {
        this.consumerGroup = consumerGroup;
    }

    public ConsumeFromWhere getConsumeFromWhere() {
        return consumeFromWhere;
    }

    public void setConsumeFromWhere(ConsumeFromWhere consumeFromWhere) {
        if (consumeFromWhere != ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET
            && consumeFromWhere != ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET
            && consumeFromWhere != ConsumeFromWhere.CONSUME_FROM_TIMESTAMP) {
            throw new RuntimeException("Invalid ConsumeFromWhere Value", null);
        }
        this.consumeFromWhere = consumeFromWhere;
    }

    public String getConsumeTimestamp() {
        return consumeTimestamp;
    }

    public void setConsumeTimestamp(String consumeTimestamp) {
        this.consumeTimestamp = consumeTimestamp;
    }

    public TraceDispatcher getTraceDispatcher() {
        return traceDispatcher;
    }

    private void setTraceDispatcher() {
        if (enableTrace) {

View on GitHub (pinned to 293f588571)

Solutions

1. Pass one of the three whitelisted constants, most commonly ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET
2. If the value comes from config, default it when null: Optional.ofNullable(cfg).orElse(ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET)
3. Avoid adding custom constants to the ConsumeFromWhere enum — the setter rejects them

Example fix

// before
consumer.setConsumeFromWhere(ConsumeFromWhere.valueOf(userConfig)); // may be null/unknown

// after
ConsumeFromWhere where = userConfig != null ? userConfig : ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET;
consumer.setConsumeFromWhere(where);

private static final Set<ConsumeFromWhere> LITE_VALID = EnumSet.of(
    ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET,
    ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET,
    ConsumeFromWhere.CONSUME_FROM_TIMESTAMP);

ConsumeFromWhere safe = (cfg == null || !LITE_VALID.contains(cfg))
    ? ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET : cfg;
consumer.setConsumeFromWhere(safe);

static boolean isValidLiteConsumeFromWhere(ConsumeFromWhere v) {
    return v == ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET
        || v == ConsumeFromWhere.CONSUME_FROM_LAST_OFFSET
        || v == ConsumeFromWhere.CONSUME_FROM_TIMESTAMP;
}

When it happens

Trigger: Calling defaultLitePullConsumer.setConsumeFromWhere(null), or with a value obtained from untyped config/serialization that decodes to null or an unknown enum constant.

Common situations: Reading consumeFromWhere from a properties/YAML file into the enum with valueOf (throws earlier) or a lenient mapper returning null; sharing a config loader between DefaultMQPushConsumer (which allows the same three) and the lite consumer after adding a custom enum constant.

Related errors

• consumerGroup can not equal
• 16
• add subscription exception
• messageModel is null
• allocateMessageQueueStrategy is null

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/094237caa13c8c0b. Report an issue: GitHub.