{"record":{"id":"a3c29bd562db865e","repo":"nats-io/nats-server","slug":"stream-write-error-v","errorCode":null,"errorMessage":"stream write error: %v","messagePattern":"stream write error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_cluster.go","lineNumber":1060,"sourceCode":"\tcase replicas <= 1:\n\t\treturn nil // No further checks for R=1 streams\n\n\tcase node == nil:\n\t\treturn errors.New(\"group node missing\")\n\n\tcase msetNode == nil:\n\t\t// Can happen when the stream's node is not yet initialized.\n\t\treturn errors.New(\"stream node missing\")\n\n\tcase node != msetNode:\n\t\ts.Warnf(\"Detected stream cluster node skew '%s > %s'\", acc.GetName(), streamName)\n\t\treturn errors.New(\"cluster node skew detected\")\n\n\tcase nrgWerr != nil:\n\t\treturn fmt.Errorf(\"node write error: %v\", nrgWerr)\n\n\tcase streamWerr != nil:\n\t\treturn fmt.Errorf(\"stream write error: %v\", streamWerr)\n\n\tcase !mset.isMonitorRunning():\n\t\treturn errors.New(\"monitor goroutine not running\")\n\n\tcase mset.isCatchingUp():\n\t\treturn errors.New(\"stream catching up\")\n\n\tcase !node.Healthy():\n\t\treturn errors.New(\"group node unhealthy\")\n\n\tdefault:\n\t\treturn nil\n\t}\n}\n\n// isConsumerHealthy will determine if the consumer is up to date.\n// For R1 it will make sure the consunmer is present on this server.\nfunc (js *jetStream) isConsumerHealthy(mset *stream, consumer string, ca *consumerAssignment) error {","sourceCodeStart":1042,"sourceCodeEnd":1078,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_cluster.go#L1042-L1078","documentation":"During the stream health check, the stream-level raft/meta write returned an error (streamWerr) — the write affecting the stream's state in its raft group failed. Reported as 'stream write error' wrapping the cause, distinguishing it from the node (nrg) write failure.","triggerScenarios":"Replicating or persisting stream state failed during health check (peer offline, quorum loss); storage backend returned an error while writing stream state; stream is mid-restore/migration and its raft group is not accepting writes.","commonSituations":"FileStorage directory permission or disk-full problems; network partitions isolating replicas; performing health checks immediately after a stream restore or scale-out before replication catches up.","solutions":["Inspect the wrapped error to identify whether it is storage- or network-related and fix that layer (disk, permissions, connectivity)","Verify all replica peers are online and replicating; restore quorum if peers are down","Re-run the health check after the cluster stabilizes; transient partition errors self-heal","If the stream is stuck mid-restore, restart the restore or recreate the stream from a backup"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// check storage health and replica connectivity before health check\nif diskUsage(raftDir) > 0.9 { alert(\"raft dir nearly full\") }\n","typeGuard":"func isStreamWriteErr(err error) bool { return strings.HasPrefix(err.Error(), \"stream write error\") }\n","tryCatchPattern":"if err := healthz(); err != nil && strings.HasPrefix(err.Error(), \"stream write error\") {\n    // inspect wrapped cause: storage vs network; retry after remediation\n}\n","preventionTips":["Monitor disk space/IO on FileStorage directories","Keep all replicas online; replace failed peers promptly","Re-run health checks after restores/migrations complete"],"tags":["jetstream","raft","health-check","stream-state"],"backgroundTag":"jetstream-raft-write-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}