apache/rocketmq · error · MQClientException

unknown exception

Error message

unknown exception

What it means

MQClientException('unknown exception') thrown by sendOneway when the underlying sendDefaultImpl raised an MQBrokerException - the broker actively returned an error response. ONEWAY normally ignores responses, but the remoting layer still surfaces broker-side errors, and sendOneway wraps them in this generic message (MQBrokerException cannot be declared on sendOneway's signature). The response code and remark of the cause carry the real diagnosis (e.g. MESSAGE_ILLEGAL, TOPIC_NOT_EXIST, SUBSCRIPTION_GROUP_NOT_EXIST, disk-full FLUSH_DISK_TIMEOUT).

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/producer/DefaultMQProducerImpl.java:1216

            context.setProducerGroup(defaultMQProducer.getProducerGroup());
            context.setBrokerAddr(brokerAddr);
            context.setMessage(msg);
            context.setMsgId(msgId);
            context.setTransactionId(msg.getTransactionId());
            context.setTransactionState(state);
            context.setFromTransactionCheck(fromTransactionCheck);
            executeEndTransactionHook(context);
        }
    }

    /**
     * DEFAULT ONEWAY -------------------------------------------------------
     */
    public void sendOneway(Message msg) throws MQClientException, RemotingException, InterruptedException {
        try {
            this.sendDefaultImpl(msg, CommunicationMode.ONEWAY, null, this.defaultMQProducer.getSendMsgTimeout());
        } catch (MQBrokerException e) {
            throw new MQClientException("unknown exception", e);
        }
    }

    /**
     * KERNEL SYNC -------------------------------------------------------
     */
    public SendResult send(Message msg, MessageQueue mq)
        throws MQClientException, RemotingException, MQBrokerException, InterruptedException {
        return send(msg, mq, this.defaultMQProducer.getSendMsgTimeout());
    }

    public SendResult send(Message msg, MessageQueue mq, long timeout)
        throws MQClientException, RemotingException, MQBrokerException, InterruptedException {
        long beginStartTime = System.currentTimeMillis();
        this.makeSureStateOK();
        Validators.checkMessage(msg, this.defaultMQProducer);

        if (!msg.getTopic().equals(mq.getTopic())) {

View on GitHub (pinned to 293f588571)

Solutions

1. Inspect the cause: ((MQBrokerException) e.getCause()).getResponseCode() and getResponseRemark() tell exactly why the broker refused
2. Fix per the code: shrink/split message (check maxMessageSize on broker), create topic, fix ACL/permissions, or free disk / relax flush-disk settings
3. Consider whether ONEWAY is right: if you need to react to broker rejections, use SYNC send and handle SendResult
4. Add logging around sendOneway that unwraps and records MQBrokerException causes instead of swallowing them

Example fix

// before
try { producer.sendOneway(msg); } catch (MQClientException e) { log.error("send failed", e); }
// after
try { producer.sendOneway(msg); }
catch (MQClientException e) {
    Throwable c = e.getCause();
    if (c instanceof MQBrokerException) log.error("broker rejected: code={} remark={}", ((MQBrokerException) c).getResponseCode(), ((MQBrokerException) c).getResponseRemark());
    else log.error("send failed", e);
}

 // pre-validate what the broker will check
if (msg.getBody().length > producer.getMaxMessageSize()) {
    throw new IllegalArgumentException("body exceeds maxMessageSize=" + producer.getMaxMessageSize());
}

try {
    producer.sendOneway(msg);
} catch (MQClientException e) {
    if (e.getCause() instanceof MQBrokerException) {
        MQBrokerException be = (MQBrokerException) e.getCause();
        log.error("broker rejected oneway: code={} remark={}", be.getResponseCode(), be.getResponseRemark());
        handleBrokerRejection(be); // dedup on message key if re-sending
    } else throw e;
}

When it happens

Trigger: triggerScenarios

Common situations: commonSituations

Related errors

• 13
• Sending message to topic[%s] is forbidden.
• sendMessage call timeout
• pullAsync unknown exception
• The producer group[{producerGroup}] has been created before,

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