{"record":{"id":"8b3cfc3b279ef8b5","repo":"hashicorp/nomad","slug":"failed-to-receive-initial-message-v","errorCode":null,"errorMessage":"failed to receive initial message: %v","messagePattern":"failed to receive initial message: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/shared/executor/grpc_server.go","lineNumber":174,"sourceCode":"\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tout, exit, err := s.impl.Exec(deadline, req.Cmd, req.Args)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn &proto.ExecResponse{\n\t\tOutput:   out,\n\t\tExitCode: int32(exit),\n\t}, nil\n}\n\nfunc (s *grpcExecutorServer) ExecStreaming(server proto.Executor_ExecStreamingServer) error {\n\tmsg, err := server.Recv()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to receive initial message: %v\", err)\n\t}\n\n\tif msg.Setup == nil {\n\t\treturn fmt.Errorf(\"first message should always be setup\")\n\t}\n\n\treturn s.impl.ExecStreaming(server.Context(),\n\t\tmsg.Setup.Command, msg.Setup.Tty,\n\t\tserver)\n}\n","sourceCodeStart":156,"sourceCodeEnd":185,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/shared/executor/grpc_server.go#L156-L185","documentation":"In the executor's streaming exec gRPC service, the first message from the client must carry the Setup payload (command, tty flag). This error means server.Recv() on the stream failed before any message arrived, so the session could not be initialized.","triggerScenarios":"Client closes or aborts the ExecStreaming gRPC stream immediately after opening it; network interruption between the Nomad client and executor; client-side timeout before sending the setup message; gRPC transport errors (connection reset, TLS failure).","commonSituations":"Unstable network between Nomad agent and executor plugin; user cancels a `nomad alloc exec` session instantly; grpc client context deadline exceeded before sending setup; proxy/LB terminating idle streams.","solutions":["Check network connectivity/TLS between the Nomad client and the executor endpoint","Ensure the client sends the Setup message immediately after opening the stream and before awaiting responses","Increase client-side gRPC timeouts and keepalive settings if the stream is dropped prematurely","Inspect client logs for cancellation/errors (io.EOF, context canceled) to identify who closed the stream"],"exampleFix":"// before\nstream, _ := client.ExecStreaming(ctx)\n// ... long delay or early return before sending setup ...\n// after\nstream, err := client.ExecStreaming(ctx)\nif err != nil { return err }\nif err := stream.Send(&proto.ExecTaskStreamingRequest{Setup: setupMsg}); err != nil { return err }","handlingStrategy":"retry","validationCode":"if connState != grpc connectivity.Ready { wait/reconnect before opening stream }","typeGuard":null,"tryCatchPattern":"stream, err := client.ExecStreaming(ctx)\nif err != nil { return err }\nif err := stream.Send(setupReq); err != nil { return err } // send immediately\n// server side: on 'failed to receive initial message', retry opening a fresh stream","preventionTips":["Send the Setup message immediately after opening the stream","Use gRPC keepalives for long-lived exec streams","Avoid opening streams you may cancel before setup"],"tags":["grpc","streaming","exec"],"backgroundTag":"grpc-stream-receive-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}