apache/rocketmq · error · IllegalStateException

The consumer not running, please start it first.

Error message

The consumer not running, please start it first.

What it means

IllegalStateException thrown by DefaultLitePullConsumerImpl.checkServiceState() when an operation requiring a RUNNING consumer (commit, seek, pause, resume, assignment updates, etc.) is invoked while the consumer is in CREATE_JUST, SHUTDOWN_ALREADY or START_FAILED state. It is a lifecycle misuse guard: the internal state machine has not reached RUNNING.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java:202

            }
        }
    }

    public void executeHookAfter(final ConsumeMessageContext context) {
        if (!this.consumeMessageHookList.isEmpty()) {
            for (ConsumeMessageHook hook : this.consumeMessageHookList) {
                try {
                    hook.consumeMessageAfter(context);
                } catch (Throwable e) {
                    log.error("consumeMessageHook {} executeHookAfter exception", hook.hookName(), e);
                }
            }
        }
    }

    private void checkServiceState() {
        if (this.serviceState != ServiceState.RUNNING) {
            throw new IllegalStateException(NOT_RUNNING_EXCEPTION_MESSAGE);
        }
    }

    public void updateNameServerAddr(String newAddresses) {
        this.mQClientFactory.getMQClientAPIImpl().updateNameServerAddressList(newAddresses);
    }

    private synchronized void setSubscriptionType(SubscriptionType type) {
        if (this.subscriptionType == SubscriptionType.NONE) {
            this.subscriptionType = type;
        } else if (this.subscriptionType != type) {
            throw new IllegalStateException(SUBSCRIPTION_CONFLICT_EXCEPTION_MESSAGE);
        }
    }

    private void updateAssignedMessageQueue(String topic, Set<MessageQueue> assignedMessageQueue) {
        this.assignedMessageQueue.updateAssignedMessageQueue(topic, assignedMessageQueue);
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Call consumer.start() and let it complete before seek/commit/pause operations
2. Do not reuse the instance after shutdown() — create a new DefaultLitePullConsumer
3. Wrap start() in try/catch and abort application startup on failure instead of continuing
4. Ensure seek/commit calls are issued from the same thread or after the start barrier (CountDownLatch on a started flag)
5. If triggered intermittently, check another thread isn't shutting the consumer down concurrently

Example fix

// before
consumer.subscribe("T", "*");
consumer.seek(mq, 0); // IllegalStateException: not RUNNING yet
consumer.start();

// after
consumer.subscribe("T", "*");
consumer.start();
consumer.seek(mq, 0);

// gate state-dependent calls behind a started flag
private final AtomicBoolean started = new AtomicBoolean(false);
// after consumer.start(): started.set(true);
public void safeSeek(MessageQueue mq, long offset) {
    if (!started.get()) throw new IllegalStateException("consumer not started");
    consumer.seek(mq, offset);
}

try {
    consumer.seek(mq, offset);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not running")) { /* start consumer first, then retry */ }
    else throw e;
}

When it happens

Trigger: Calling consumer.seek(...), commitSync/commitAsync, assign-related or pause/resume before consumer.start(), or after consumer.shutdown(). Also when start() failed midway (registerConsumer conflict) leaving state CREATE_JUST and the application ignores the exception and continues.

Common situations: Ordering bug: wiring a scheduler/REST endpoint that seeks or commits before the start() call finishes; code reuse of a consumer instance after deliberate shutdown; exception during start() swallowed so the app proceeds with a half-initialized consumer.

Related errors

• The PullConsumer service state not OK, maybe started once,
• Subscribe and assign are mutually exclusive.
• consumerGroup can not equal
• messageModel is null
• allocateMessageQueueStrategy is null

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