lima-vm/lima · error

failed to stop usernet %#q: %w

Error message

failed to stop usernet %#q: %w

What it means

Lima could not stop the running userspace network (usernet/vde) daemon for the given network when reconciling networks down. The underlying error from usernet.Stop (process kill/HTTP request to the usernet controller) is wrapped verbatim.

Source

Thrown at pkg/networks/reconcile/reconcile.go:402

// stderrHint returns the daemon's stderr (or a pointer to the log) to append to errors.
func stderrHint(stderrLog string) string {
	if b, err := os.ReadFile(stderrLog); err == nil && len(b) > 0 {
		return fmt.Sprintf(" (stderr: %s)", strings.TrimSpace(string(b)))
	}
	return fmt.Sprintf(" (check %#q)", stderrLog)
}

func stopNetwork(ctx context.Context, cfg *networks.Config, name string) error {
	logrus.Debugf("Make sure %#q network is stopped", name)
	// Handle usernet first without sudo requirements
	isUsernet, err := cfg.Usernet(name)
	if err != nil {
		return err
	}
	if isUsernet {
		if err := usernet.Stop(ctx, name); err != nil {
			return fmt.Errorf("failed to stop usernet %#q: %w", name, err)
		}
		return nil
	}

	if runtime.GOOS != "darwin" {
		return nil
	}

	// Don't call validateConfig() until we actually need to stop a daemon because
	// stopNetwork() may be called even when the daemons are not installed.
	for _, daemon := range []string{networks.SocketVMNet} {
		if ok, _ := cfg.IsDaemonInstalled(daemon); !ok {
			continue
		}
		pid, _ := store.ReadPIDFile(cfg.PIDFile(name, daemon))
		if pid != 0 {
			logrus.Infof("Stopping %s daemon for %#q network", daemon, name)
			if err := validateConfig(ctx, cfg); err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped cause to see if the process is already gone; if so, remove the stale PID file under ~/.lima and retry
2. Manually kill the leftover usernet/vde process, then run limactl start again (it reconciles state)
3. Check that no other user session owns the usernet process
4. Retry after the transient condition clears (e.g. system under heavy load)

Example fix

// before
pgrep -af usernet
kill <pid>
rm ~/.lima/networks/*_pid
// after
limactl start

if err := stopNetwork(ctx, name); err != nil {
    log.Warnf("usernet stop failed: %v; cleaning up manually", err)
    // pkill usernet/vde, remove stale PID files, continue reconciliation
}

When it happens

Trigger: Reconcile → stopNetwork for a network whose cfg.Usernet(name) is true, and usernet.Stop returns an error — e.g. the usernet controller process cannot be killed or its HTTP endpoint is unresponsive.

Common situations: An usernet daemon already crashed but the process entry is inconsistent, the usernet process is owned by another user, or the context was cancelled mid-stop.

Related errors

• failed to kill process with pid %d: %w
• usernet unable to resolve IP for SSH forwarding
• UDPFileConn connection closed
• network %#q already exists
• network mode %#q does not support specifying gateway

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/be2a20274ebff071. Report an issue: GitHub.