{"record":{"id":"18fc65e67a60aecc","repo":"cloudflare/cloudflared","slug":"failed-to-start-forwarding-server","errorCode":null,"errorMessage":"failed to start forwarding server","messagePattern":"failed to start forwarding server","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"carrier/carrier.go","lineNumber":70,"sourceCode":"\n// Write will write to Stdout\nfunc (c *StdinoutStream) Write(p []byte) (int, error) {\n\treturn os.Stdout.Write(p)\n}\n\n// Helper to allow deferring the response close with a check that the resp is not nil\nfunc closeRespBody(resp *http.Response) {\n\tif resp != nil {\n\t\t_ = resp.Body.Close()\n\t}\n}\n\n// StartForwarder will setup a listener on a specified address/port and then\n// forward connections to the origin by calling `Serve()`.\nfunc StartForwarder(conn Connection, address string, shutdownC <-chan struct{}, options *StartOptions) error {\n\tlistener, err := net.Listen(\"tcp\", address)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"failed to start forwarding server\")\n\t}\n\treturn Serve(conn, listener, shutdownC, options)\n}\n\n// StartClient will copy the data from stdin/stdout over a WebSocket connection\n// to the edge (originURL)\nfunc StartClient(conn Connection, stream io.ReadWriter, options *StartOptions) error {\n\treturn conn.ServeStream(options, stream)\n}\n\n// Serve accepts incoming connections on the specified net.Listener.\n// Each connection is handled in a new goroutine: its data is copied over a\n// WebSocket connection to the edge (originURL).\n// `Serve` always closes `listener`.\nfunc Serve(remoteConn Connection, listener net.Listener, shutdownC <-chan struct{}, options *StartOptions) error {\n\tdefer listener.Close()\n\terrChan := make(chan error)\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/carrier/carrier.go#L52-L88","documentation":"StartForwarder wraps any error from net.Listen when trying to bind the local TCP forwarding address. It means cloudflared could not set up the local listener that proxies connections to the origin over the tunnel. The wrapped underlying error (e.g. 'address already in use' or 'permission denied') is the actual cause.","triggerScenarios":"Calling StartForwarder with an address that is already bound, a privileged port (<1024) without root/CAP_NET_BIND_SERVICE, an invalid address string, or an address on an interface that does not exist.","commonSituations":"Running two cloudflared instances at once (the second fails to bind --url), firing up a second copy of a dev server on the same local port, using port 80/443 as non-root, or a misconfigured --url value with a typo in the host/IP.","solutions":["Check if another process is bound to the address/port (lsof -i :<port> or netstat) and stop it or pick a different port.","If using a privileged port, run as root, grant CAP_NET_BIND_SERVICE, or use a port >= 1024.","Verify the --url address format (host:port) and that the interface/IP exists on the machine.","Ensure only one cloudflared instance (or forwarding server) uses this address at a time."],"exampleFix":"// before\nStartForwarder(conn, \"localhost:80\", shutdownC, options)\n// after\nStartForwarder(conn, \"localhost:8080\", shutdownC, options)","handlingStrategy":"validation","validationCode":"ln, err := net.Listen(\"tcp\", address)\nif err != nil {\n\treturn fmt.Errorf(\"address %s unavailable: %w\", address, err)\n}\nln.Close() // free it before handing to StartForwarder","typeGuard":null,"tryCatchPattern":"if err := carrier.StartForwarder(conn, addr, shutdownC, opts); err != nil {\n\tvar oe *net.OpError\n\tif errors.As(err, &oe) && strings.Contains(oe.Error(), \"address already in use\") {\n\t\taddr = \"localhost:0\" // retry with ephemeral port\n\t}\n}","preventionTips":["Pick high, unprivileged ports (>=1024) for forwarding addresses.","Check port availability before starting the forwarder.","Ensure only one cloudflared instance runs per address."],"tags":["network","go","tcp-listener","port-conflict"],"backgroundTag":"address-already-in-use","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}