{"record":{"id":"16b76c7c7f3a598f","repo":"lima-vm/lima","slug":"usernet-unable-to-resolve-ip-for-ssh-forwarding","errorCode":null,"errorMessage":"usernet unable to resolve IP for SSH forwarding","messagePattern":"usernet unable to resolve IP for SSH forwarding","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/networks/usernet/client.go","lineNumber":101,"sourceCode":"\t}\n\treturn nil\n}\n\nfunc (c *Client) ResolveIPAddress(ctx context.Context, vmMacAddr string) (string, error) {\n\tresolveIPAddressTimeout := 2 * time.Minute\n\tresolveIPAddressTimeoutEnv := os.Getenv(\"LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT\")\n\tif resolveIPAddressTimeoutEnv != \"\" {\n\t\tif parsedTimeout, err := strconv.Atoi(resolveIPAddressTimeoutEnv); err == nil {\n\t\t\tresolveIPAddressTimeout = time.Duration(parsedTimeout) * time.Minute\n\t\t}\n\t}\n\tctx, cancel := context.WithTimeout(ctx, resolveIPAddressTimeout)\n\tdefer cancel()\n\tticker := time.NewTicker(500 * time.Millisecond)\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn \"\", errors.New(\"usernet unable to resolve IP for SSH forwarding\")\n\t\tcase <-ticker.C:\n\t\t\tleases, err := c.Leases(ctx)\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", err\n\t\t\t}\n\n\t\t\tfor ipAddr, leaseAddr := range leases {\n\t\t\t\tif vmMacAddr == leaseAddr {\n\t\t\t\t\treturn ipAddr, nil\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n\nfunc (c *Client) Leases(ctx context.Context) (map[string]string, error) {\n\tu := fmt.Sprintf(\"%s%s\", c.base, \"/services/dhcp/leases\")\n\tres, err := httpclientutil.Get(ctx, c.client, u)","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/networks/usernet/client.go#L83-L119","documentation":"Lima's usernet client polled the usernet DHCP leases endpoint every 500ms for the full resolve timeout (default 2 minutes, configurable via LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT) without ever seeing a lease whose MAC address matches the VM's MAC address, so it cannot determine the guest IP for SSH port forwarding.","triggerScenarios":"ResolveIPAddress (via ConfigureDriver or WaitOpeningSSHPort) polls c.Leases(ctx) until ctx.Done() fires with no matching MAC — the VM never obtained a DHCP lease on the usernet network, or the MAC address doesn't match the lease entries.","commonSituations":"Guest failed to boot or to run DHCP, the instance's MAC address changed vs. recorded leases, usernet's DHCP server not assigning leases (broken vde/udpvmnet backend), or slow guests exceeding the 2-minute default timeout (fixable by raising LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT).","solutions":["Increase the timeout: export LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT=5 (minutes) and retry","Check the guest actually booted and requested DHCP (limactl shell <instance>; ip link / dhclient), inspect limactl logs","Verify the VM's MAC address matches what usernet leases report; restart the instance to re-trigger DHCP","Recreate the instance if its network state is wedged: limactl delete <instance> && limactl start <template>"],"exampleFix":"// before\nlimactl start  # times out after 2 min resolving IP\n// after\nexport LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT=5\nlimactl start","handlingStrategy":"retry","validationCode":"// raise the resolve window before starting slow-booting guests\nos.Setenv(\"LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT\", \"5\") // minutes","typeGuard":null,"tryCatchPattern":"ip, err := client.ResolveIPAddress(ctx, macAddr)\nif err != nil {\n    if errors.Is(err, context.DeadlineExceeded) || strings.Contains(err.Error(), \"unable to resolve IP\") {\n        // retry with longer timeout, or verify the guest booted & DHCP ran\n    }\n}","preventionTips":["Set LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT for slow-booting guests","Ensure the guest actually performs DHCP on the usernet interface","Verify the VM MAC address used for the lease lookup matches the instance config","Watch usernet logs; recreate the instance if leases never appear"],"tags":["network","usernet","dhcp","timeout","ssh-forwarding"],"backgroundTag":"dhcp-lease-not-found","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}