{"record":{"id":"842cb7fb00607ea4","repo":"chenhg5/cc-connect","slug":"cloud-web-gateway-listen-w","errorCode":null,"errorMessage":"cloud_web: gateway listen: %w","messagePattern":"cloud_web: gateway listen: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"platform/cloud-web/gateway.go","lineNumber":95,"sourceCode":"\tt.caps = caps\n\tt.mu.Unlock()\n}\n\nfunc (t *gatewayTransport) Start(ctx context.Context, onInbound inboundHandler) error {\n\tt.onInbound = onInbound\n\trunCtx, cancel := context.WithCancel(ctx)\n\tt.cancel = cancel\n\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(t.webhookPath, t.webhookHandler)\n\tt.server = &http.Server{\n\t\tHandler:           mux,\n\t\tReadHeaderTimeout: 10 * time.Second,\n\t}\n\tln, err := net.Listen(\"tcp\", t.listen)\n\tif err != nil {\n\t\tcancel()\n\t\treturn fmt.Errorf(\"cloud_web: gateway listen: %w\", err)\n\t}\n\tt.listener = ln\n\n\tgo func() {\n\t\tslog.Info(\"cloud_web: gateway webhook listening\", \"addr\", ln.Addr().String(), \"path\", t.webhookPath)\n\t\tif err := t.server.Serve(ln); err != nil && err != http.ErrServerClosed {\n\t\t\tslog.Error(\"cloud_web: gateway server error\", \"error\", err)\n\t\t}\n\t}()\n\n\tif t.registerURL != \"\" {\n\t\tcaps, err := t.register(runCtx)\n\t\tif err != nil {\n\t\t\tslog.Warn(\"cloud_web: gateway register failed\", \"error\", err)\n\t\t} else {\n\t\t\tt.setCaps(caps)\n\t\t}\n\t}","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/cloud-web/gateway.go#L77-L113","documentation":"The cloud-web platform's gateway transport failed to bind its inbound webhook HTTP listener when Platform.Start() was called. The transport opens a TCP listener (default :8099) so the cloud-web bridge can POST events to it; if net.Listen fails the whole Start fails and the platform cannot start. The wrapped OS error tells you exactly why the bind failed.","triggerScenarios":"Calling Start (e.g. via cc-connect startup) when the configured listen address is already in use by another process, the port is privileged (below 1024) without permissions, the address is invalid/unresolvable, or an instance of cc-connect is already running with the same listen setting.","commonSituations":"Duplicate cc-connect instance from a stale systemd/launchd service; another dev server squatting on :8099; listen set to ':80' or ':443' in config.toml; Docker container networking the port twice; typo like 'localhost::8099'.","solutions":["Find and stop the process holding the port (lsof -i :8099 or ss -ltnp), or kill the stale cc-connect instance.","Change the listen value in the cloud-web platform section of config.toml to a free port (e.g. \":8100\").","If binding a privileged port, run as root, use CAP_NET_BIND_SERVICE, or put a reverse proxy in front.","Verify the listen string syntax: '[host]:port', e.g. ':8099' or '127.0.0.1:8099'."],"exampleFix":"// config.toml — before\n[[platform]]\nname = \"cloud-web\"\nlisten = \":8099\"   # fails: address already in use\n\n// after\n[[platform]]\nname = \"cloud-web\"\nlisten = \":8123\"   # free port","handlingStrategy":"validation","validationCode":"// before calling Start, check the port is free\nconn, err := net.Listen(\"tcp\", \":8099\")\nif err != nil {\n    return fmt.Errorf(\"port :8099 unavailable: %w\", err)\n}\nconn.Close() // close and let Start bind it","typeGuard":null,"tryCatchPattern":"if err := platform.Start(ctx, handler); err != nil {\n    var opErr *net.OpError\n    if errors.As(err, &opErr) && errors.Is(opErr.Err, syscall.EADDRINUSE) {\n        slog.Error(\"gateway port in use; stop the other instance or change listen\", \"error\", err)\n    }\n    return err\n}","preventionTips":["Reserve a dedicated, uncommon port for the gateway listen address","Ensure only one cc-connect instance runs per host (systemd/launchd singleton)","Validate the listen address syntax ([host]:port) before deployment","Never bind privileged ports without the required capabilities"],"tags":["network","port-binding","go","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}