{"record":{"id":"5af0ed7de551e1d2","repo":"abiosoft/colima","slug":"port-d-is-already-in-use","errorCode":null,"errorMessage":"port %d is already in use","messagePattern":"port (.+?) is already in use","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/model.go","lineNumber":206,"sourceCode":"\t\t// Determine the port to use\n\t\tport := modelCmdArgs.ServePort\n\t\tportExplicitlySet := cmd.Flags().Changed(\"port\")\n\n\t\t// If port was not explicitly set, find an available port starting from the default\n\t\tconst maxPortAttempts = 20\n\t\tif !portExplicitlySet {\n\t\t\tavailablePort, found := util.FindAvailablePort(port, maxPortAttempts)\n\t\t\tif !found {\n\t\t\t\treturn fmt.Errorf(\"no available port found in range %d-%d\", port, port+maxPortAttempts-1)\n\t\t\t}\n\t\t\tif availablePort != port {\n\t\t\t\tfmt.Printf(\"Port %d is in use, using port %d instead\\n\", port, availablePort)\n\t\t\t}\n\t\t\tport = availablePort\n\t\t} else {\n\t\t\t// User explicitly set the port, check if it's available\n\t\t\tif _, found := util.FindAvailablePort(port, 1); !found {\n\t\t\t\treturn fmt.Errorf(\"port %d is already in use\", port)\n\t\t\t}\n\t\t}\n\n\t\t// Build header for alternate screen\n\t\tseparator := \"────────────────────────────────────────\"\n\t\theader := fmt.Sprintf(\"Colima - Model Server (Ctrl-C to stop)\\nWeb UI & API at http://localhost:%d\\n%s\", port, separator)\n\n\t\t// Run in alternate screen with header\n\t\treturn terminal.WithAltScreen(func() error {\n\t\t\treturn runner.Serve(normalizedModel, port)\n\t\t}, header)\n\t},\n}\n\nfunc init() {\n\troot.Cmd().AddCommand(modelCmd)\n\tmodelCmd.AddCommand(modelSetupCmd)\n\tmodelCmd.AddCommand(modelServeCmd)","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/cmd/model.go#L188-L224","documentation":"When --port IS passed to `colima model serve`, the CLI probes exactly that one port (FindAvailablePort(port, 1)) and refuses to start if something already listens on it. Unlike the no-flag path there is no fallback scanning: an explicitly requested port must be free, because the user pinned it deliberately (e.g. for a stable URL).","triggerScenarios":"Passing --port that matches a running service: another model serve instance, a local web server, a container publishing the same port, or a bound-but-not-yet-released socket from a serve process that just exited.","commonSituations":"Restarting `colima model serve` while the previous instance still holds the port; a port copied from docker -p mappings colliding with host services; fixed-port automation colliding across profiles.","solutions":["Identify and stop the holder: `lsof -nP -i tcp:<port>`, kill it, retry","Choose a different port: `colima model serve --port <other>`","Omit --port entirely to let colima auto-pick the first free port in its 20-port scan range"],"exampleFix":"# before\n$ colima model serve --port 8080\nerror: port 8080 is already in use\n\n# after\n$ lsof -nP -i tcp:8080   # -> kill <pid>\n$ colima model serve --port 8080","handlingStrategy":"retry","validationCode":"// confirm the chosen port is bindable BEFORE launching serve\nfunc portFree(port int) bool {\n    l, err := net.Listen(\"tcp\", fmt.Sprintf(\":%d\", port))\n    if err != nil {\n        return false\n    }\n    return l.Close() == nil\n}\n\nif !portFree(wanted) {\n    // kill the holder (lsof -nP -i tcp:<port>) or pick another port\n}","typeGuard":null,"tryCatchPattern":"var re = regexp.MustCompile(`port (\\d+) is already in use`)\nif err := serveCmd.Execute(); err != nil {\n    if m := re.FindStringSubmatch(err.Error()); m != nil {\n        port, _ := strconv.Atoi(m[1])\n        _ = port // retry with port+1, or free the holder first\n    }\n}","preventionTips":["Check `lsof -nP -i tcp:<port>` before passing --port","Ensure the previous serve instance fully exited (port released) before restarting with the same port","In scripts, fall back to omitting --port so colima auto-scans"],"tags":["colima","llm","network","ports","cli"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}