{"record":{"id":"30d60e4291977cdb","repo":"yudai/gotty","slug":"failed-to-setup-an-http-server","errorCode":null,"errorMessage":"failed to setup an HTTP server","messagePattern":"failed to setup an HTTP server","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/server.go","lineNumber":106,"sourceCode":"// existing connections. Use WithGracefullContext() to support gracefull shutdown.\nfunc (server *Server) Run(ctx context.Context, options ...RunOption) error {\n\tcctx, cancel := context.WithCancel(ctx)\n\topts := &RunOptions{gracefullCtx: context.Background()}\n\tfor _, opt := range options {\n\t\topt(opts)\n\t}\n\n\tcounter := newCounter(time.Duration(server.options.Timeout) * time.Second)\n\n\tpath := \"/\"\n\tif server.options.EnableRandomUrl {\n\t\tpath = \"/\" + randomstring.Generate(server.options.RandomUrlLength) + \"/\"\n\t}\n\n\thandlers := server.setupHandlers(cctx, cancel, path, counter)\n\tsrv, err := server.setupHTTPServer(handlers)\n\tif err != nil {\n\t\treturn errors.Wrapf(err, \"failed to setup an HTTP server\")\n\t}\n\n\tif server.options.PermitWrite {\n\t\tlog.Printf(\"Permitting clients to write input to the PTY.\")\n\t}\n\tif server.options.Once {\n\t\tlog.Printf(\"Once option is provided, accepting only one client\")\n\t}\n\n\tif server.options.Port == \"0\" {\n\t\tlog.Printf(\"Port number configured to `0`, choosing a random port\")\n\t}\n\thostPort := net.JoinHostPort(server.options.Address, server.options.Port)\n\tlistener, err := net.Listen(\"tcp\", hostPort)\n\tif err != nil {\n\t\treturn errors.Wrapf(err, \"failed to listen at `%s`\", hostPort)\n\t}\n","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/yudai/gotty/blob/a080c85cbc59226c94c6941ad8c395232d72d517/server/server.go#L88-L124","documentation":"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.","triggerScenarios":"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).","commonSituations":"Running with enable_tls_client_auth but tls_ca_crt_file points to a nonexistent or malformed file; permission denied on the CA file.","solutions":["Read the wrapped inner error to identify the real cause","If using TLS client auth, verify the CA cert file exists, is readable, and contains valid PEM certificates","Fix the underlying option (correct path or valid cert) and retry"],"exampleFix":"// before (file missing)\nenable_tls_client_auth = true\ntls_ca_crt_file = \"~/missing-ca.crt\"\n// after\nenable_tls_client_auth = true\ntls_ca_crt_file = \"~/.gotty/ca.crt\"","handlingStrategy":"try-catch","validationCode":"if opts.EnableTLSClientAuth {\n    if _, err := os.Stat(homeDir(opts.TLSCACrtFile)); err != nil {\n        log.Fatalf(\"CA cert unreadable: %v\", err)\n    }\n}","typeGuard":null,"tryCatchPattern":"err := server.Run(ctx)\nif err != nil && strings.Contains(err.Error(), \"failed to setup an HTTP server\") {\n    log.Fatalf(\"HTTP server setup failed: %v\", err)\n}","preventionTips":["Pre-validate TLS options before Run()","Log the full wrapped error chain to find the root cause"],"tags":["http","tls","startup"],"backgroundTag":"http-server-setup-failed","analyzedSha":"a080c85cbc59226c94c6941ad8c395232d72d517","analyzedAt":"2026-09-02T16:42:38.150Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}