{"record":{"id":"a3abfa4a1df79bf2","repo":"apache/pulsar","slug":"transaction-recover-tracker","errorCode":null,"errorMessage":"Transaction recover tracker`","messagePattern":"Transaction recover tracker`","errorType":"validation","errorClass":"InvalidTxnStatusException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/transaction/recover/TransactionRecoverTrackerImpl.java","lineNumber":106,"sourceCode":"    @Override\n    public void updateTransactionStatus(long sequenceId, TxnStatus txnStatus) throws InvalidTxnStatusException {\n        switch (txnStatus) {\n            case COMMITTING:\n                openTransactions.remove(sequenceId);\n                committingTransactions.add(sequenceId);\n                break;\n            case ABORTING:\n                openTransactions.remove(sequenceId);\n                abortingTransactions.add(sequenceId);\n                break;\n            case ABORTED:\n                abortingTransactions.remove(sequenceId);\n                break;\n            case COMMITTED:\n                committingTransactions.remove(sequenceId);\n                break;\n            default:\n                throw new InvalidTxnStatusException(\"Transaction recover tracker`\"\n                        + new TxnID(tcId, sequenceId) + \"` load replay metadata operation \"\n                        + \"from transaction log with unknown operation\");\n        }\n    }\n\n    @Override\n    public void handleOpenStatusTransaction(long sequenceId, long timeout) {\n        openTransactions.put(sequenceId, timeout);\n    }\n\n    @Override\n    public void appendOpenTransactionToTimeoutTracker() {\n        openTransactions.forEach(timeoutTracker::replayAddTransaction);\n    }\n\n    @Override\n    public void handleCommittingAndAbortingTransaction() {\n        committingTransactions.forEach(k ->","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/transaction/recover/TransactionRecoverTrackerImpl.java#L88-L124","documentation":"TransactionRecoverTrackerImpl.updateTransactionStatus replays entries from the transaction log and applies COMMITTING/ABORTING/COMMITTED/ABORTED status changes. It throws InvalidTxnStatusException when the replayed operation/status is unknown, indicating the transaction log contains metadata this tracker cannot interpret. This is a fail-fast guard so a corrupt or foreign log entry does not silently misstate a transaction's status.","triggerScenarios":"Replaying a transaction log entry whose op/status is not one of COMMITTING, ABORTING, COMMITTED, ABORTED — typically a corrupt entry, a partially-written log record, or an entry written by a newer Pulsar version than the one replaying it.","commonSituations":"Cluster version skew during rolling upgrade; corrupted transaction log ledger after unclean broker shutdown; manual edits or tooling writing raw entries to the transaction log.","solutions":["Identify the tcId/sequenceId in the message and inspect the corresponding transaction log entry","Confirm all brokers run a consistent Pulsar version that understands the log's operation codes","Check the transaction log ledger for corruption; use managed-ledger recovery/repair tooling if entries are damaged","If corruption is confirmed, move the affected transaction log to a recovery ledger per Pulsar transaction recovery docs and restart"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-check: read the transaction log entry's op field and confirm it is one of\n// COMMITTING, ABORTING, COMMITTED, ABORTED before invoking updateTransactionStatus.","typeGuard":null,"tryCatchPattern":"try {\n    tracker.updateTransactionStatus(tcId, sequenceId, op);\n} catch (InvalidTxnStatusException e) {\n    log.error(\"Unknown transaction log operation for txn {}:{}\", tcId, sequenceId, e);\n    // stop recovery and escalate for manual ledger inspection\n}","preventionTips":["Avoid version skew between brokers writing and replaying the transaction log","Verify ledger integrity after unclean shutdowns before recovery","Never write raw entries into the transaction log with external tooling","Upgrade all brokers before new transaction log op codes are introduced"],"tags":["transaction","recovery","replay","invalid-status"],"backgroundTag":"transaction-replay-illegal-state","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}