{"record":{"id":"74902375528afca4","repo":"nats-io/nats-server","slug":"could-not-decode-avl-dmap-v","errorCode":null,"errorMessage":"could not decode avl dmap: %v","messagePattern":"could not decode avl dmap: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/filestore.go","lineNumber":10191,"sourceCode":"\t}\n\n\t// Check for consistency if accounting. If something is off bail and we will rebuild.\n\tif mb.msgs != (atomic.LoadUint64(&mb.last.seq)-atomic.LoadUint64(&mb.first.seq)+1)-dmapLen {\n\t\tos.Remove(ifn)\n\t\treturn fmt.Errorf(\"accounting inconsistent\")\n\t}\n\n\t// Checksum\n\tcopy(mb.lchk[0:], buf[bi:bi+checksumSize])\n\tbi += checksumSize\n\n\t// Now check for presence of a delete map\n\tif dmapLen > 0 {\n\t\t// New version is encoded avl seqset.\n\t\tif buf[1] == newVersion {\n\t\t\tdmap, _, err := avl.Decode(buf[bi:])\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"could not decode avl dmap: %v\", err)\n\t\t\t}\n\t\t\tmb.dmap = *dmap\n\t\t} else {\n\t\t\t// This is the old version.\n\t\t\tfor i, fseq := 0, atomic.LoadUint64(&mb.first.seq); i < int(dmapLen); i++ {\n\t\t\t\tseq := readSeq()\n\t\t\t\tif seq == 0 {\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t\tmb.dmap.Insert(seq + fseq)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// Will return total number of cache loads.","sourceCodeStart":10173,"sourceCodeEnd":10209,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/filestore.go#L10173-L10209","documentation":"This error wraps a failure from avl.Decode() when parsing a delete-map encoded as an AVL seqset (new version message block format). The delete map records which message sequences in the message block have been deleted; if the on-disk bytes are unreadable or malformed, the message block cannot be loaded. NATS JetStream file storage throws this when recovering a stream from disk with a corrupted or truncated delete-map section.","triggerScenarios":"Loading a message block (mb) during file store recovery where buf[1] == newVersion and dmapLen > 0, and avl.Decode(buf[bi:]) fails due to corrupt/truncated bytes in the delete-map region.","commonSituations":"Disk corruption or partial writes after a crash; manually copied or truncated stream data directories; version mismatches where a data file was edited or migrated incorrectly.","solutions":["Verify disk integrity (fsck, smartctl) and restore the stream from backup or snapshots.","Let JetStream rebuild the stream: delete the stream's data directory (or use stream reset) and republish or re-sync data from upstream.","Confirm the filestore version on disk matches the server version; run the same or newer NATS server that wrote the data.","Enable JetStream recovery logging and check for preceding I/O errors indicating failing storage hardware."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Go: check the wrapped cause\nif err != nil {\n    if strings.Contains(err.Error(), \"could not decode avl dmap\") {\n        log.Printf(\"stream data corrupt, plan recovery: %v\", err)\n        // trigger restore / stream rebuild\n    }\n}","preventionTips":["Use clean shutdown and UPS/journaling storage to avoid torn writes","Never copy or rsync a live JetStream StoreDir; use snapshot APIs","Run regular stream integrity checks and keep backups","Keep the nats-server version at or above the version that wrote the data"],"tags":["jetstream","filestore","corruption","deserialization"],"backgroundTag":"stream-data-corruption","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}