{"record":{"id":"af283d280742ba0e","repo":"apache/rocketmq","slug":"readlocaloffset-exception-maybe-fastjson-version","errorCode":null,"errorMessage":"readLocalOffset Exception, maybe fastjson version too low\nSee https://rocketmq.apache.org/docs/faq/ for further details.","messagePattern":"readLocalOffset Exception, maybe fastjson version too low\nSee https://rocketmq\\.apache\\.org/docs/faq/ for further details\\.","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/consumer/store/LocalFileOffsetStore.java","lineNumber":267,"sourceCode":"            return offsetSerializeWrapper;\n        }\n    }\n\n    private OffsetSerializeWrapper readLocalOffsetBak() throws MQClientException {\n        String content = null;\n        try {\n            content = MixAll.file2String(this.storePath + \".bak\");\n        } catch (IOException e) {\n            log.warn(\"Load local offset store bak file exception\", e);\n        }\n        if (content != null && content.length() > 0) {\n            OffsetSerializeWrapper offsetSerializeWrapper = null;\n            try {\n                offsetSerializeWrapper =\n                    OffsetSerializeWrapper.fromJson(content, OffsetSerializeWrapper.class);\n            } catch (Exception e) {\n                log.warn(\"readLocalOffset Exception\", e);\n                throw new MQClientException(\"readLocalOffset Exception, maybe fastjson version too low\"\n                    + FAQUrl.suggestTodo(FAQUrl.LOAD_JSON_EXCEPTION),\n                    e);\n            }\n            return offsetSerializeWrapper;\n        }\n\n        return null;\n    }\n}\n","sourceCodeStart":249,"sourceCodeEnd":277,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/consumer/store/LocalFileOffsetStore.java#L249-L277","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Align fastjson to the version the client POM expects (check dependency tree for downgrades)","If offsets matter, snapshot the file first and use admin APIs (queryConsumerOffset) to restore committed offsets after restart"],"exampleFix":"// shell recovery\nmv ~/.rocketmq_offsets/dev/myGroup.json{,.corrupt}\nmv ~/.rocketmq_offsets/dev/myGroup.json.bak{,.corrupt}\n# restart consumer; offsets re-initialized per consumeFromWhere","handlingStrategy":"fallback","validationCode":"// Detect a corrupt offset file before the store reads it\nPath p = Paths.get(System.getProperty(\"user.home\"),\n    \".rocketmq_offsets\", instanceName, group + \".json.bak\");\nif (Files.exists(p)) {\n    try {\n        new com.alibaba.fastjson.JSON().parseObject(Files.readString(p));\n    } catch (Exception corrupt) {\n        Files.move(p, p.resolveSibling(group + \".json.bak.corrupt\"));\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    consumer.start();\n} catch (MQClientException e) {\n    if (e.getMessage().contains(\"readLocalOffset\")) {\n        // quarantine offset files and restart; offsets rebuild from broker/consumeFromWhere\n    }\n}","preventionTips":["Pin fastjson to the client POM's version in your dependencyManagement","For durable offsets prefer remote (broker) offset storage over local files in production","Keep backups of offset files before client upgrades"],"tags":["offsets","serialization","fastjson","consumer","recovery"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}