apache/rocketmq · error · MQClientException

readLocalOffset Exception, maybe fastjson version too low Se

Error message

readLocalOffset Exception, maybe fastjson version too low
See https://rocketmq.apache.org/docs/faq/ for further details.

What it means

LocalFileOffsetStore.readLocalOffset re-reads the local offset backup file (<storePath>.bak) when the primary is unusable, and throws this MQClientException when its JSON cannot be deserialized into OffsetSerializeWrapper. Historically the most common cause was an old fastjson version that could not parse the wrapper's map format, hence the message pointing at the fastjson FAQ. Corrupted/truncated offset files also land here.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/consumer/store/LocalFileOffsetStore.java:267

            return offsetSerializeWrapper;
        }
    }

    private OffsetSerializeWrapper readLocalOffsetBak() throws MQClientException {
        String content = null;
        try {
            content = MixAll.file2String(this.storePath + ".bak");
        } catch (IOException e) {
            log.warn("Load local offset store bak file exception", e);
        }
        if (content != null && content.length() > 0) {
            OffsetSerializeWrapper offsetSerializeWrapper = null;
            try {
                offsetSerializeWrapper =
                    OffsetSerializeWrapper.fromJson(content, OffsetSerializeWrapper.class);
            } catch (Exception e) {
                log.warn("readLocalOffset Exception", e);
                throw new MQClientException("readLocalOffset Exception, maybe fastjson version too low"
                    + FAQUrl.suggestTodo(FAQUrl.LOAD_JSON_EXCEPTION),
                    e);
            }
            return offsetSerializeWrapper;
        }

        return null;
    }
}

View on GitHub (pinned to 293f588571)

Solutions

1. Delete (or move aside) the offset file and its .bak under the store path (default ~/.rocketmq_offsets/<instanceName>/<group>.json) — offsets will be rebuilt from the broker or per consumeFromWhere
2. Align fastjson to the version the client POM expects (check dependency tree for downgrades)
3. If offsets matter, snapshot the file first and use admin APIs (queryConsumerOffset) to restore committed offsets after restart

Example fix

// shell recovery
mv ~/.rocketmq_offsets/dev/myGroup.json{,.corrupt}
mv ~/.rocketmq_offsets/dev/myGroup.json.bak{,.corrupt}
# restart consumer; offsets re-initialized per consumeFromWhere

// Detect a corrupt offset file before the store reads it
Path p = Paths.get(System.getProperty("user.home"),
    ".rocketmq_offsets", instanceName, group + ".json.bak");
if (Files.exists(p)) {
    try {
        new com.alibaba.fastjson.JSON().parseObject(Files.readString(p));
    } catch (Exception corrupt) {
        Files.move(p, p.resolveSibling(group + ".json.bak.corrupt"));
    }
}

try {
    consumer.start();
} catch (MQClientException e) {
    if (e.getMessage().contains("readLocalOffset")) {
        // quarantine offset files and restart; offsets rebuild from broker/consumeFromWhere
    }
}

When it happens

Trigger: OFFSET_READ_FROM_STORE / local-offset mode consumers (e.g. DefaultLitePullConsumer or pull consumers with local offset storage) restarting, finding a .bak offset file whose JSON is corrupt or written by an incompatible serialization version.

Common situations: Process killed mid-write leaving a truncated file; upgrading the client across serialization changes; a fastjson dependency clash on the classpath pulling in an older version than the client needs; disk issues corrupting the JSON.

Related errors

• The broker[${brokerName}] not exist
• Invalid ConsumeFromWhere Value
• add subscription exception
• Can not find Message Queue for this topic, ${topic} Namesrv
• Can not find Message Queue for this topic, ${topic} See http

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