failed to authenticate websocket connection: invalid…

Error message

failed to authenticate websocket connection: invalid message type

What it means

Guard in processWSConn rejecting the auth handshake because the first message arrived as a binary (or non-text) websocket frame instead of the expected TextMessage carrying the JSON credentials. The fault is the client's framing, not the payload contents.

Solutions

Ensure the client sends its auth JSON as a websocket text frame, not binary
Upgrade client libraries that default to binary frames (e.g. some Go/JS ws configs)
Close the connection with a policy-violation close code so the client can self-correct

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/handlers.go:96 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

AI-assisted analysis of yudai/gotty@a080c85cbc (2026-09-02). Data as JSON: /api/errors/118d0d622701eabe. Report an issue: GitHub.

Appendix: source

Thrown at server/handlers.go:96

		case ctx.Err():
			closeReason = "cancelation"
		case webtty.ErrSlaveClosed:
			closeReason = server.factory.Name()
		case webtty.ErrMasterClosed:
			closeReason = "client"
		default:
			closeReason = fmt.Sprintf("an error: %s", err)
		}
	}
}

func (server *Server) processWSConn(ctx context.Context, conn *websocket.Conn) error {
	typ, initLine, err := conn.ReadMessage()
	if err != nil {
		return errors.Wrapf(err, "failed to authenticate websocket connection")
	}
	if typ != websocket.TextMessage {
		return errors.New("failed to authenticate websocket connection: invalid message type")
	}

	var init InitMessage
	err = json.Unmarshal(initLine, &init)
	if err != nil {
		return errors.Wrapf(err, "failed to authenticate websocket connection")
	}
	if init.AuthToken != server.options.Credential {
		return errors.New("failed to authenticate websocket connection")
	}

	queryPath := "?"
	if server.options.PermitArguments && init.Arguments != "" {
		queryPath = init.Arguments
	}

	query, err := url.Parse(queryPath)
	if err != nil {

View on GitHub (pinned to a080c85cbc)