hashicorp/nomad · error

wsErr.Text

Error message

wsErr.Text

What it means

When receiving from the exec websocket, a *websocket.CloseError with a non-empty Text is converted to a plain error carrying the server-supplied close reason; it fires when the Nomad server (or intermediate proxy) closes the exec stream and includes a human-readable explanation in the close frame.

Source

Thrown at api/allocations_exec.go:66

	conn, err := s.startConnection()
	if err != nil {
		return -2, err
	}
	defer conn.Close()

	sendErrCh := s.startTransmit(ctx, conn)
	exitCh, recvErrCh := s.startReceiving(ctx, conn)

	for {
		select {
		case <-ctx.Done():
			return -2, ctx.Err()
		case exitCode := <-exitCh:
			return exitCode, nil
		case recvErr := <-recvErrCh:
			// drop websocket code, not relevant to user
			if wsErr, ok := recvErr.(*websocket.CloseError); ok && wsErr.Text != "" {
				return -2, errors.New(wsErr.Text)
			}

			return -2, recvErr
		case sendErr := <-sendErrCh:
			return -2, fmt.Errorf("failed to send input: %w", sendErr)
		}
	}
}

func (s *execSession) startConnection() (*websocket.Conn, error) {
	// First, attempt to connect to the node directly, but may fail due to network isolation
	// and network errors.  Fallback to using server-side forwarding instead.
	nodeClient, err := s.client.GetNodeClientWithTimeout(s.alloc.NodeID, ClientConnTimeout, s.q)
	if err == NodeDownErr {
		return nil, NodeDownErr
	}

	q := s.q

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the returned text for the server's close reason (e.g. auth failure, task exit, connection lost)
2. Re-establish the exec session and retry the command
3. Check Nomad agent and network/proxy health between client and server

When it happens

Trigger: Thrown at api/allocations_exec.go:66 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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