hashicorp/nomad · error

failed to receive initial message: %v

Error message

failed to receive initial message: %v

What it means

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.

Source

Thrown at drivers/shared/executor/grpc_server.go:174

	if err != nil {
		return nil, err
	}

	out, exit, err := s.impl.Exec(deadline, req.Cmd, req.Args)
	if err != nil {
		return nil, err
	}

	return &proto.ExecResponse{
		Output:   out,
		ExitCode: int32(exit),
	}, nil
}

func (s *grpcExecutorServer) ExecStreaming(server proto.Executor_ExecStreamingServer) error {
	msg, err := server.Recv()
	if err != nil {
		return fmt.Errorf("failed to receive initial message: %v", err)
	}

	if msg.Setup == nil {
		return fmt.Errorf("first message should always be setup")
	}

	return s.impl.ExecStreaming(server.Context(),
		msg.Setup.Command, msg.Setup.Tty,
		server)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check network connectivity/TLS between the Nomad client and the executor endpoint
2. Ensure the client sends the Setup message immediately after opening the stream and before awaiting responses
3. Increase client-side gRPC timeouts and keepalive settings if the stream is dropped prematurely
4. Inspect client logs for cancellation/errors (io.EOF, context canceled) to identify who closed the stream

Example fix

// before
stream, _ := client.ExecStreaming(ctx)
// ... long delay or early return before sending setup ...
// after
stream, err := client.ExecStreaming(ctx)
if err != nil { return err }
if err := stream.Send(&proto.ExecTaskStreamingRequest{Setup: setupMsg}); err != nil { return err }

if connState != grpc connectivity.Ready { wait/reconnect before opening stream }

stream, err := client.ExecStreaming(ctx)
if err != nil { return err }
if err := stream.Send(setupReq); err != nil { return err } // send immediately
// server side: on 'failed to receive initial message', retry opening a fresh stream

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• failed to receive initial message: %v
• first message should always be setup
• task driver does not support exec
• failed to attach to exec: %v
• first message should always be setup

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/8b3cfc3b279ef8b5. Report an issue: GitHub.