{"record":{"id":"56281fc17ba34032","repo":"nats-io/nats-server","slug":"bad-index-file","errorCode":null,"errorMessage":"bad index file","messagePattern":"bad index file","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/filestore.go","lineNumber":10130,"sourceCode":"\t\treturn err\n\t}\n\n\t// Set if first time.\n\tif mb.liwsz == 0 {\n\t\tmb.liwsz = int64(len(buf))\n\t}\n\n\t// Decrypt if needed.\n\tif mb.aek != nil {\n\t\tbuf, err = mb.aek.Open(buf[:0], mb.nonce, buf, nil)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif err := checkNewHeader(buf); err != nil {\n\t\tdefer os.Remove(ifn)\n\t\treturn fmt.Errorf(\"bad index file\")\n\t}\n\n\tbi := hdrLen\n\n\t// Helpers, will set i to -1 on error.\n\treadSeq := func() uint64 {\n\t\tif bi < 0 {\n\t\t\treturn 0\n\t\t}\n\t\tseq, n := binary.Uvarint(buf[bi:])\n\t\tif n <= 0 {\n\t\t\tbi = -1\n\t\t\treturn 0\n\t\t}\n\t\tbi += n\n\t\treturn seq &^ ebit\n\t}\n\treadCount := readSeq","sourceCodeStart":10112,"sourceCodeEnd":10148,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/filestore.go#L10112-L10148","documentation":"Returned when a file-store block index file fails header validation on load: checkNewHeader rejects the file's header block. The store removes the bad index file and returns this error so the caller can trigger an index rebuild.","triggerScenarios":"Reading an index file (ifn) whose header fails checkNewHeader — the file's magic/header bytes don't match the expected new-format header.","commonSituations":"Upgraded/downgraded NATS Server versions writing different index formats, truncated or corrupted index files after power loss, or partially restored data directories from backup.","solutions":["Simply retry/restart — the index file is deleted automatically and will be rebuilt from the message block.","If the server version changed, confirm the data directory matches the current NATS Server version's expectations.","If rebuilds keep failing, stop the server, back up the stream dir, and remove *.idx files to force a clean rebuild.","Check disk/filesystem integrity if corruption recurs frequently."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"bad index file\") {\n    // index was deleted; server rebuilds it automatically — verify stream reads recover\n}","preventionTips":["Don't mix data directories across NATS Server major versions without following upgrade docs.","Use UPS-backed clean shutdowns to avoid truncated files.","Back up stream directories only while the server is stopped.","Monitor for repeated index rebuilds — a sign of underlying storage corruption."],"tags":["filestore","index","corruption","jetstream","go"],"backgroundTag":"bad-index-file","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}