abiosoft/colima · error

port %d is already in use

Error message

port %d is already in use

What it means

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).

Source

Thrown at cmd/model.go:206

		// Determine the port to use
		port := modelCmdArgs.ServePort
		portExplicitlySet := cmd.Flags().Changed("port")

		// If port was not explicitly set, find an available port starting from the default
		const maxPortAttempts = 20
		if !portExplicitlySet {
			availablePort, found := util.FindAvailablePort(port, maxPortAttempts)
			if !found {
				return fmt.Errorf("no available port found in range %d-%d", port, port+maxPortAttempts-1)
			}
			if availablePort != port {
				fmt.Printf("Port %d is in use, using port %d instead\n", port, availablePort)
			}
			port = availablePort
		} else {
			// User explicitly set the port, check if it's available
			if _, found := util.FindAvailablePort(port, 1); !found {
				return fmt.Errorf("port %d is already in use", port)
			}
		}

		// Build header for alternate screen
		separator := "────────────────────────────────────────"
		header := fmt.Sprintf("Colima - Model Server (Ctrl-C to stop)\nWeb UI & API at http://localhost:%d\n%s", port, separator)

		// Run in alternate screen with header
		return terminal.WithAltScreen(func() error {
			return runner.Serve(normalizedModel, port)
		}, header)
	},
}

func init() {
	root.Cmd().AddCommand(modelCmd)
	modelCmd.AddCommand(modelSetupCmd)
	modelCmd.AddCommand(modelServeCmd)

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Identify and stop the holder: `lsof -nP -i tcp:<port>`, kill it, retry
2. Choose a different port: `colima model serve --port <other>`
3. Omit --port entirely to let colima auto-pick the first free port in its 20-port scan range

Example fix

# before
$ colima model serve --port 8080
error: port 8080 is already in use

# after
$ lsof -nP -i tcp:8080   # -> kill <pid>
$ colima model serve --port 8080

// confirm the chosen port is bindable BEFORE launching serve
func portFree(port int) bool {
    l, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
    if err != nil {
        return false
    }
    return l.Close() == nil
}

if !portFree(wanted) {
    // kill the holder (lsof -nP -i tcp:<port>) or pick another port
}

var re = regexp.MustCompile(`port (\d+) is already in use`)
if err := serveCmd.Execute(); err != nil {
    if m := re.FindStringSubmatch(err.Error()); m != nil {
        port, _ := strconv.Atoi(m[1])
        _ = port // retry with port+1, or free the holder first
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• no available port found in range %d-%d
• no models available Pull a model first: colima model pull ai
• model name is required for ramalama runner Usage: colima mod
• %s is not running
• %s is not enabled

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/5af0ed7de551e1d2. Report an issue: GitHub.