{"record":{"id":"8c3976499441d8bd","repo":"nats-io/nats-server","slug":"maximum-replicas-is-d","errorCode":null,"errorMessage":"maximum replicas is %d","messagePattern":"maximum replicas is (.+?)","errorType":"error_code","errorClass":"JSStreamInvalidConfigError","httpStatus":null,"severity":"error","filePath":"server/stream.go","lineNumber":1915,"sourceCode":"\t\treturn cfg, NewJSStreamInvalidConfigError(fmt.Errorf(\"invalid discard policy\"))\n\t}\n\tif _, err := cfg.Compression.MarshalJSON(); err != nil {\n\t\treturn cfg, NewJSStreamInvalidConfigError(fmt.Errorf(\"invalid compression\"))\n\t}\n\n\t// Make file the default.\n\tif cfg.Storage == 0 {\n\t\tcfg.Storage = FileStorage\n\t}\n\tif _, err := cfg.Storage.MarshalJSON(); err != nil {\n\t\treturn cfg, NewJSStreamInvalidConfigError(fmt.Errorf(\"invalid storage type\"))\n\t}\n\n\tif cfg.Replicas == 0 {\n\t\tcfg.Replicas = 1\n\t}\n\tif cfg.Replicas > StreamMaxReplicas {\n\t\treturn cfg, NewJSStreamInvalidConfigError(fmt.Errorf(\"maximum replicas is %d\", StreamMaxReplicas))\n\t}\n\tif cfg.Replicas < 0 {\n\t\treturn cfg, NewJSReplicasCountCannotBeNegativeError()\n\t}\n\tif cfg.MaxMsgs == 0 || cfg.MaxMsgs < -1 {\n\t\tif pedantic && cfg.MaxMsgs < -1 {\n\t\t\treturn StreamConfig{}, NewJSPedanticError(fmt.Errorf(\"max_msgs must be set to -1\"))\n\t\t}\n\t\tcfg.MaxMsgs = -1\n\t}\n\tif cfg.MaxMsgsPer == 0 || cfg.MaxMsgsPer < -1 {\n\t\tif pedantic && cfg.MaxMsgsPer < -1 {\n\t\t\treturn StreamConfig{}, NewJSPedanticError(fmt.Errorf(\"max_msgs_per_subject must be set to -1\"))\n\t\t}\n\t\tcfg.MaxMsgsPer = -1\n\t}\n\tif cfg.MaxBytes == 0 || cfg.MaxBytes < -1 {\n\t\tif pedantic && cfg.MaxBytes < -1 {","sourceCodeStart":1897,"sourceCodeEnd":1933,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream.go#L1897-L1933","documentation":"JetStream stream configuration validation rejects a stream whose Replicas count exceeds StreamMaxReplicas (the server's maximum supported R for mirrored/clustered streams). The server wraps it in a JSStreamInvalidConfigError during stream config normalization. This prevents creating or updating a stream with a replication factor the server cannot support.","triggerScenarios":"Calling stream create/update API (JS API $JS.API.STREAM.CREATE/UPDATE) with config.replicas set higher than StreamMaxReplicas; e.g. submitting replicas=10 when the server max is lower. Occurs in the server-side config check (server/stream.go:1915) before the stream is persisted.","commonSituations":"Copy-pasted config from another deployment (e.g. cloud with higher replica cap); misreading replicas as 'number of servers'; accidental multiplication in config templating; upgrading clients that allow higher R than this server version supports.","solutions":["Lower the stream's Replicas in the StreamConfig to a value <= StreamMaxReplicas (check the constant in your server version)","If you need higher replication, upgrade the nats-server to a version with a higher StreamMaxReplicas","If clusters/servers are the real intent, use raft placement/placement tags rather than inflating replicas"],"exampleFix":"// before\ncfg := jetstream.StreamConfig{Name: \"ORDERS\", Replicas: 10}\n// after\ncfg := jetstream.StreamConfig{Name: \"ORDERS\", Replicas: 3}","handlingStrategy":"validation","validationCode":"if cfg.Replicas < 0 || cfg.Replicas > jetstream.MaxReplicasCap { // check your server's StreamMaxReplicas\n    return fmt.Errorf(\"replicas %d exceeds server maximum\", cfg.Replicas)\n}","typeGuard":null,"tryCatchPattern":"err := createStream(cfg)\nvar apiErr *nats.APIError\nif errors.As(err, &apiErr) && apiErr.ErrorCode == nats.ErrorCodeJetStreamInvalidStreamConfig {\n    // surface a config-fix hint to the user\n}","preventionTips":["Cap Replicas in your config templates to the lowest supported maximum","Read the constant from the server version you deploy against, not from client defaults","Validate stream configs in CI before applying to production"],"tags":["jetstream","stream-config","validation","nats-server"],"backgroundTag":"jetstream-invalid-stream-config","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}