yudai/gotty · error

failed to create webtty

Error message

failed to create webtty

What it means

Wrapped error from webtty.New: one of the functional options passed when constructing the terminal session (preferences marshaling, title, reconnect, etc.) rejected the configuration, so the WebTTY instance could not be built for this connection.

Source

Thrown at server/handlers.go:163

	if server.options.PermitWrite {
		opts = append(opts, webtty.WithPermitWrite())
	}
	if server.options.EnableReconnect {
		opts = append(opts, webtty.WithReconnect(server.options.ReconnectTime))
	}
	if server.options.Width > 0 {
		opts = append(opts, webtty.WithFixedColumns(server.options.Width))
	}
	if server.options.Height > 0 {
		opts = append(opts, webtty.WithFixedRows(server.options.Height))
	}
	if server.options.Preferences != nil {
		opts = append(opts, webtty.WithMasterPreferences(server.options.Preferences))
	}

	tty, err := webtty.New(&wsWrapper{conn}, slave, opts...)
	if err != nil {
		return errors.Wrapf(err, "failed to create webtty")
	}

	err = tty.Run(ctx)

	return err
}

func (server *Server) handleIndex(w http.ResponseWriter, r *http.Request) {
	titleVars := server.titleVariables(
		[]string{"server", "master"},
		map[string]map[string]interface{}{
			"server": server.options.TitleVariables,
			"master": map[string]interface{}{
				"remote_addr": r.RemoteAddr,
			},
		},
	)

View on GitHub (pinned to a080c85cbc)

Solutions

1. Inspect the wrapped option error to find which With* option failed
2. Validate Preferences JSON-marshals at config load time rather than per-connection
3. Log the option name and offending value to pinpoint misconfiguration

When it happens

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

Common situations: See trigger scenarios.

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