{"record":{"id":"5a63ce31fbdbd29a","repo":"grafana/k6","slug":"failed-to-create-a-new-stream-w","errorCode":null,"errorMessage":"failed to create a new stream: %w","messagePattern":"failed to create a new stream: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/js/modules/k6/grpc/stream.go","lineNumber":101,"sourceCode":"\t\tMethod:                 s.method,\n\t\tMethodDescriptor:       s.methodDescriptor,\n\t\tDiscardResponseMessage: p.DiscardResponseMessage,\n\t\tTagsAndMeta:            &p.TagsAndMeta,\n\t\tMetadata:               p.Metadata,\n\t}\n\n\tctx := s.vu.Context()\n\tvar cancel context.CancelFunc\n\n\tif p.Timeout != time.Duration(0) {\n\t\tctx, cancel = context.WithTimeout(ctx, p.Timeout)\n\t}\n\n\ts.timeoutCancel = cancel\n\n\tstream, err := s.client.conn.NewStream(ctx, *req)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create a new stream: %w\", err)\n\t}\n\ts.stream = stream\n\tmetrics.PushIfNotDone(s.vu.Context(), s.vu.State().Samples, metrics.Sample{\n\t\tTimeSeries: metrics.TimeSeries{\n\t\t\tMetric: s.instanceMetrics.Streams,\n\t\t\tTags:   s.tagsAndMeta.Tags,\n\t\t},\n\t\tTime:     time.Now(),\n\t\tMetadata: s.tagsAndMeta.Metadata,\n\t\tValue:    1,\n\t})\n\n\tgo s.loop()\n\n\treturn nil\n}\n\nfunc (s *stream) loop() {","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/grafana/k6/blob/93accf6570dcd306ca5e99cc44c393ee3797761b/internal/js/modules/k6/grpc/stream.go#L83-L119","documentation":"Thrown by k6's gRPC streaming API when client.newStream(method, params) cannot establish the underlying gRPC stream. beginStream (internal/js/modules/k6/grpc/stream.go:99-102) calls conn.NewStream with the VU context (wrapped in a context.WithTimeout if a params.timeout was given) and wraps any failure with %w, so the tail of the message carries the real grpc-go cause (connection refused, TLS handshake error, unavailable, deadline exceeded, etc.).","triggerScenarios":"Server is down or the address/port is wrong (rpc error: connection refused); TLS mismatch — e.g. connecting with plaintext:true to a TLS endpoint or vice versa; calling newStream before a successful client.connect(); a params.timeout that expires during stream setup (context deadline exceeded); the method name not matching a loaded service (stream mode on a method that is not a streaming RPC).","commonSituations":"Load testing a staging gRPC service that requires mTLS (missing tls.cert/key in connect params); typo in the method string ('/pkg.Service/Method' format); server behind a proxy that breaks HTTP/2; timeout set too low for slow TLS handshakes; reusing a client whose connection was closed after a prior error.","solutions":["Read the wrapped cause after the colon: 'connection refused' means address/port; 'authentication handshake failed' or 'x509' means TLS config; 'deadline exceeded' means params.timeout.","Verify the server with a plain client.invoke() call — if invoke also fails, the problem is in connect(), not the stream.","For TLS servers, align connect params: remove plaintext:true, add tls: { cacerts: ... } (and cert/key for mTLS).","Increase the stream timeout: client.newStream(method, { timeout: '30s' }) or set connect timeout.","Confirm the method string exactly matches the proto service path and that the method is a server/client streaming RPC."],"exampleFix":"// before\nclient.connect('grpc.example.com:443', { plaintext: true });\nconst stream = client.newStream('chat.ChatService/Connect'); // failed to create a new stream: ... handshake failure\n\n// after\nclient.connect('grpc.example.com:443', { tls: { cacerts: [caPem] } });\nconst stream = client.newStream('chat.ChatService/Connect', { timeout: '30s' });","handlingStrategy":"try-catch","validationCode":"// Cheap connectivity pre-check is not possible for gRPC streams; validate configuration instead.\nfunction assertStreamConfig(client, method) {\n  if (!method.startsWith('/') || method.split('/').length !== 3) throw new Error(`invalid gRPC method '${method}', expected '/pkg.Service/Method'`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const stream = client.newStream('/svc.Method/stream', { timeout: '30s' });\n  stream.on('error', (e) => console.log(`stream error: ${e}`));\n} catch (err) {\n  const cause = String(err.message).split(':').pop().trim();\n  if (/refused|unavailable/.test(cause)) { /* server down: record failure, abort scenario */ }\n  else if (/handshake|x509/.test(cause)) { /* TLS config: fix connect params */ }\n  else if (/deadline/.test(cause)) { /* raise timeout and retry once */ }\n}","preventionTips":["Prove the channel with a simple client.invoke() health call before opening streams.","Always set an explicit stream timeout sized for handshake + first message.","Register an 'error' listener on every stream so transport errors surface as events, not surprises."],"tags":["grpc","streaming","network","tls","timeout"],"backgroundTag":null,"analyzedSha":"93accf6570dcd306ca5e99cc44c393ee3797761b","analyzedAt":"2026-08-15T21:23:27.118Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}