{"record":{"id":"30566e3351760660","repo":"nats-io/nats-server","slug":"failed-to-read-consumer-q-state-w","errorCode":null,"errorMessage":"failed to read consumer %q state: %w","messagePattern":"failed to read consumer %q state: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":422,"sourceCode":"\t\t\t\tif err = fmt.Errorf(\"failed to activate consumer %q: %w\", o.name, err); retErr == nil {\n\t\t\t\t\tretErr = err\n\t\t\t\t}\n\t\t\t\ts.Warnf(\"JetStream stream restore for '%s > %s' failed to activate consumers: %v\", a.Name, cfg.Name, err)\n\t\t\t}\n\t\t}\n\t}()\n\tfor range nstate.Consumers {\n\t\thdr, err := tr.Next()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tname, found := strings.CutPrefix(hdr.Name, \"consumers/\")\n\t\tif !found {\n\t\t\treturn nil, fmt.Errorf(\"expected consumer, found %q\", hdr.Name)\n\t\t}\n\t\tbuf, err := io.ReadAll(tr)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to read consumer %q state: %w\", name, err)\n\t\t}\n\t\tvar consumer SnapshotConsumerState\n\t\tif err := json.Unmarshal(buf, &consumer); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to decode consumer %q state: %w\", name, err)\n\t\t}\n\t\tif consumer.ConsumerConfig == nil {\n\t\t\treturn nil, fmt.Errorf(\"consumer %q is missing config\", name)\n\t\t}\n\t\tif consumer.ConsumerState == nil {\n\t\t\treturn nil, fmt.Errorf(\"consumer %q is missing state\", name)\n\t\t}\n\t\tisEphemeral := !isDurableConsumer(consumer.ConsumerConfig)\n\t\tif isEphemeral {\n\t\t\t// Keep ephemerals alive and interested until all messages have\n\t\t\t// been restored, then start their normal inactivity lifecycle.\n\t\t\tconsumer.Durable = name\n\t\t}\n\t\to, err := mset.addConsumerForRestore(consumer.ConsumerConfig)","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L404-L440","documentation":"Reading the body of a 'consumers/<name>' archive entry with io.ReadAll failed, so the consumer's snapshot state could not be loaded; the restore aborts with the consumer name in the message. As with 951, the raw I/O cause is not wrapped — the underlying reader error surfaced from the s2/tar stream.","triggerScenarios":"The compressed bytes for a consumer entry are truncated or corrupt: interrupted backup, partial file transfer, bit-flip corruption in the s2 stream, or a connection drop while streaming the restore request body to STREAM.RESTORE.","commonSituations":"Large backups transferred over flaky networks; snapshots copied with `cp` while the source backup was still being written; corrupted files on unreliable storage; restore requests aborted mid-stream by proxies with body-size/timeout limits.","solutions":["Re-take or re-transfer the backup and verify checksums before restoring","Remove proxy/upload size or timeout limits blocking large restore bodies, or restore the consumer state via direct file placement on the server","Compare the archive size against the original snapshot; a mismatch confirms truncation — re-download","If only one consumer entry is corrupt and consumers are dispensable, regenerate the snapshot without it (or use `nats stream backup --consumers=false`)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if want, got := expectedChecksum, fileChecksum(snapshotPath); want != got {\n    return fmt.Errorf(\"snapshot corrupt/truncated; refusing restore\")\n}","typeGuard":null,"tryCatchPattern":"_, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to read consumer\") {\n        // archive unreadable mid-entry: re-transfer snapshot and retry\n    }\n    return err\n}","preventionTips":["Checksum snapshots after transfer and before restore","Let backups finish before copying; copy only closed files","Raise proxy/body limits for large restore requests","Use retries with resumable transfer for snapshots over unreliable networks"],"tags":["jetstream","stream-restore","io-error","consumer"],"backgroundTag":"truncated-backup-file","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}