{"record":{"id":"6ac084b3e32772a9","repo":"abiosoft/colima","slug":"failed-to-start-port-forwarder-w","errorCode":null,"errorMessage":"failed to start port forwarder: %w","messagePattern":"failed to start port forwarder: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"model/docker.go","lineNumber":235,"sourceCode":"\n\t// Find the GGUF file path (handles both Docker registry and HuggingFace models)\n\tggufPath, err := findGGUFPath(guest, modelHash)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not find GGUF file for model %q: %w\", cfg.ModelName, err)\n\t}\n\n\t// Get container IP\n\tcontainerIP, err := getDockerModelRunnerIP(guest)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// Kill any existing socat on this port\n\tstopSocat(guest, cfg.Port)\n\n\t// Start socat in background to forward localhost:port → container_ip:port\n\tif err := startSocat(guest, cfg.Port, containerIP); err != nil {\n\t\treturn fmt.Errorf(\"failed to start port forwarder: %w\", err)\n\t}\n\n\t// Run llama-server interactively (blocking, with visible output)\n\t// Ctrl-C will be received by the interactive process directly\n\t// Use -it for TTY, -i for non-TTY (e.g., piped or CI environments)\n\texecFlag := \"-i\"\n\tif terminal.IsTerminal() {\n\t\texecFlag = \"-it\"\n\t}\n\n\terr = guest.RunInteractive(\"docker\", \"exec\", execFlag, \"docker-model-runner\",\n\t\t\"/app/bin/com.docker.llama-server\",\n\t\t\"-ngl\", fmt.Sprintf(\"%d\", cfg.GPULayers),\n\t\t\"--metrics\",\n\t\t\"--threads\", fmt.Sprintf(\"%d\", cfg.Threads),\n\t\t\"--model\", ggufPath,\n\t\t\"--alias\", cfg.ModelName,\n\t\t\"--host\", \"0.0.0.0\",","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/model/docker.go#L217-L253","documentation":"ServeDockerModel forwards the host port to the runner container by running, inside the VM, `nohup socat TCP-LISTEN:<port>,fork,reuseaddr TCP:<containerIP>:<port> &` via guest.Run(\"sh\",\"-c\",cmd). This error means that shell command exited non-zero: socat is not installed in the VM guest, the port is already bound (a leftover socat that stopSocat failed to kill, or another service), or sh reported an error.","triggerScenarios":"Choosing a port already LISTENing in the VM (previous serve's socat survived stopSocat, or another daemon owns it); guest image lacking /usr/bin/socat; containerIP unreachable so socat exits immediately (less common since nohup backgrounds it).","commonSituations":"Repeated serves on the same port after an unclean exit; ports like 8080 that other VM services use; minimal/custom colima images without socat.","solutions":["Kill leftovers in the VM and retry: colima ssh -- 'pkill -f \"socat TCP-LISTEN:<port>\"'","Serve on a different, likely-free port (cfg.Port)","Check socat exists in the guest: colima ssh -- which socat; if missing, install it in the guest or use an image that includes it","Verify what holds the port: colima ssh -- 'ss -ltnp | grep <port>'"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before startSocat: confirm the guest port is free and socat exists.\nfunc portForwardPrecheck(guest environment.VM, port int) error {\n    if guest.RunQuiet(\"sh\", \"-c\", fmt.Sprintf(\"command -v socat >/dev/null\")) != nil {\n        return fmt.Errorf(\"socat not installed in VM\")\n    }\n    if guest.RunQuiet(\"sh\", \"-c\", fmt.Sprintf(\"! ss -ltn | grep -q ':%d '\", port)) != nil {\n        return fmt.Errorf(\"port %d already in use in VM\", port)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := startSocat(guest, cfg.Port, containerIP); err != nil {\n    _ = stopSocat(guest, cfg.Port) // clear any half-started listener\n    return fmt.Errorf(\"failed to start port forwarder: %w — is socat installed and port %d free?\", err, cfg.Port)\n}","preventionTips":["Pick uncommon ports for serve to avoid collisions with VM services","After an interrupted serve, pkill socat in the VM before serving again on the same port","Verify socat presence in the guest image when building custom colima images"],"tags":["socat","port-forwarding","network","docker"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}