{"record":{"id":"515a252a5d7d37f3","repo":"lima-vm/lima","slug":"invalid-ssh-local-port-d","errorCode":null,"errorMessage":"invalid ssh local port %d","messagePattern":"invalid ssh local port (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/hostagent/hostagent.go","lineNumber":327,"sourceCode":"\t\tsshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)\n\t}\n\tif err := sshutil.Format(b, sshPath, instName, sshutil.FormatConfig,\n\t\tappend(sshOpts,\n\t\t\tfmt.Sprintf(\"Hostname=%s\", instSSHAddress),\n\t\t\tfmt.Sprintf(\"Port=%d\", sshLocalPort),\n\t\t)); err != nil {\n\t\treturn err\n\t}\n\tfileName := filepath.Join(instDir, filenames.SSHConfig)\n\treturn os.WriteFile(fileName, b.Bytes(), 0o600)\n}\n\nfunc determineSSHLocalPort(confLocalPort int, instName, limaVersion string) (int, error) {\n\tif confLocalPort > 0 {\n\t\treturn confLocalPort, nil\n\t}\n\tif confLocalPort < 0 {\n\t\treturn 0, fmt.Errorf(\"invalid ssh local port %d\", confLocalPort)\n\t}\n\tif versionutil.LessThan(limaVersion, \"2.0.0\") && instName == \"default\" {\n\t\t// use hard-coded value for \"default\" instance, for backward compatibility\n\t\treturn 60022, nil\n\t}\n\tsshLocalPort, err := freeport.TCP()\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"failed to find a free port, try setting `ssh.localPort` manually: %w\", err)\n\t}\n\treturn sshLocalPort, nil\n}\n\nfunc (a *HostAgent) emitEvent(_ context.Context, ev events.Event) {\n\ta.eventEncMu.Lock()\n\tdefer a.eventEncMu.Unlock()\n\n\ta.statusMu.Lock()\n\ta.currentStatus = ev.Status","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/hostagent/hostagent.go#L309-L345","documentation":"determineSSHLocalPort validates the configured ssh.localPort: a positive value is used as-is, zero means auto-pick, but a negative value is rejected outright as invalid. This is a config sanity check before any port allocation is attempted.","triggerScenarios":"Starting an instance whose config (lima.yaml ssh.localPort or stored instance config) contains a negative SSH local port value, via limactl start → hostagent.New → determineSSHLocalPort.","commonSituations":"Typo in ssh.localPort (e.g. -2222); template variable substitution yielding a negative number; a migration or hand-edit writing a sentinel negative value that older Lima versions tolerated.","solutions":["Set ssh.localPort to a positive port (e.g. 60022) or remove the key entirely to let Lima auto-select a free port","Fix the value in ~/.lima/<instance>/lima.yaml or the source template","Run 'limactl validate' on the config before starting"],"exampleFix":"// before (lima.yaml)\nssh:\n  localPort: -1\n// after\nssh:\n  localPort: 60022","handlingStrategy":"validation","validationCode":"// guard the configured port before starting\nif conf, ok := sshCfg[\"localPort\"].(int); ok && conf < 0 {\n\treturn fmt.Errorf(\"ssh.localPort must be >= 0, got %d\", conf)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use port numbers 1-65535 in ssh.localPort; omit the key for auto-selection","Run 'limactl validate' on configs containing explicit ports","Beware template variables that could substitute negative values","Keep ssh.localPort unset (0) unless you specifically need a fixed port"],"tags":["ssh","port","config","validation"],"backgroundTag":"invalid-port-configuration","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}