yudai/gotty · error

failed to setup an HTTP server

Error message

failed to setup an HTTP server

What it means

Run() builds its HTTP server via setupHTTPServer(); any error from that step is wrapped with this message. It indicates the in-process HTTP handler/server construction failed, before any listening happens. The root cause is carried in the wrapped error.

Source

Thrown at server/server.go:106

// existing connections. Use WithGracefullContext() to support gracefull shutdown.
func (server *Server) Run(ctx context.Context, options ...RunOption) error {
	cctx, cancel := context.WithCancel(ctx)
	opts := &RunOptions{gracefullCtx: context.Background()}
	for _, opt := range options {
		opt(opts)
	}

	counter := newCounter(time.Duration(server.options.Timeout) * time.Second)

	path := "/"
	if server.options.EnableRandomUrl {
		path = "/" + randomstring.Generate(server.options.RandomUrlLength) + "/"
	}

	handlers := server.setupHandlers(cctx, cancel, path, counter)
	srv, err := server.setupHTTPServer(handlers)
	if err != nil {
		return errors.Wrapf(err, "failed to setup an HTTP server")
	}

	if server.options.PermitWrite {
		log.Printf("Permitting clients to write input to the PTY.")
	}
	if server.options.Once {
		log.Printf("Once option is provided, accepting only one client")
	}

	if server.options.Port == "0" {
		log.Printf("Port number configured to `0`, choosing a random port")
	}
	hostPort := net.JoinHostPort(server.options.Address, server.options.Port)
	listener, err := net.Listen("tcp", hostPort)
	if err != nil {
		return errors.Wrapf(err, "failed to listen at `%s`", hostPort)
	}

View on GitHub (pinned to a080c85cbc)

Solutions

1. Read the wrapped inner error to identify the real cause
2. If using TLS client auth, verify the CA cert file exists, is readable, and contains valid PEM certificates
3. Fix the underlying option (correct path or valid cert) and retry

Example fix

// before (file missing)
enable_tls_client_auth = true
tls_ca_crt_file = "~/missing-ca.crt"
// after
enable_tls_client_auth = true
tls_ca_crt_file = "~/.gotty/ca.crt"

if opts.EnableTLSClientAuth {
    if _, err := os.Stat(homeDir(opts.TLSCACrtFile)); err != nil {
        log.Fatalf("CA cert unreadable: %v", err)
    }
}

err := server.Run(ctx)
if err != nil && strings.Contains(err.Error(), "failed to setup an HTTP server") {
    log.Fatalf("HTTP server setup failed: %v", err)
}

When it happens

Trigger: Calling Server.Run() when setupHTTPServer returns an error — most commonly the TLS setup failing because EnableTLSClientAuth is set and tlsConfig() fails (missing/unreadable/unparseable CA cert file).

Common situations: Running with enable_tls_client_auth but tls_ca_crt_file points to a nonexistent or malformed file; permission denied on the CA file.

Related errors

• failed to compile regular expression of Websocket Origin: %s
• failed to setup TLS configuration
• could not open CA crt file %s
• could not parse CA crt file data in %s
• Internal Server Error

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