k3s-io/k3s · critical

failed to start wranger controllers

Error message

failed to start wranger controllers

What it means

k3s server (pkg/server/server.go, apiserverControllers): after leader controllers register additional OnChange/OnRemove callbacks, sc.Start(ctx) re-runs informer factory startup so newly needed caches begin syncing against the apiserver. This panic (message contains the 'wranger' typo) fires when that informer startup fails, i.e. the apiserver could not serve the watch/list requests the new caches issued.

Source

Thrown at pkg/server/server.go:193

	return nil
}

// apiserverControllers starts the core controllers, as well as the leader-elected controllers
// that should only run on a control-plane node.
func apiserverControllers(ctx context.Context, sc *Context, config *Config) {
	if err := coreControllers(ctx, sc, config); err != nil {
		panic(err)
	}
	for _, controller := range config.LeaderControllers {
		if err := controller(ctx, sc); err != nil {
			panic(errors.WithMessagef(err, "failed to start %s leader controller", util.GetFunctionName(controller)))
		}
	}

	// Re-run informer factory startup after core and leader-elected controllers have started.
	// Additional caches may need to start for the newly added OnChange/OnRemove callbacks.
	if err := sc.Start(ctx); err != nil {
		panic(errors.WithMessage(err, "failed to start wranger controllers"))
	}
}

// runOrDie is similar to leader.RunOrDie, except that it runs the callback
// immediately, without performing leader election.
func runOrDie(ctx context.Context, name string, cb leader.Callback) {
	defer func() {
		if err := recover(); err != nil {
			logrus.WithField("stack", string(debug.Stack())).Fatalf("%s controller panic: %v", name, err)
		}
	}()
	cb(ctx)
	<-ctx.Done()
}

// coreControllers starts the following controllers, if they are enabled:
// * Node controller (manages coredns node hosts file)
// * Helm controller

View on GitHub (pinned to 6ba341e396)

Solutions

1. Verify apiserver readiness (k3s kubectl get --raw /readyz) and scan preceding k3s log lines for apiserver or datastore errors
2. Relieve pressure: free disk, raise memory limits, and check embedded datastore (etcd/sqlite) health on the node
3. Restart k3s once the apiserver reports healthy so informer factory startup re-runs
4. On persistent failure, align k3s versions and review any apiserver flag overrides (--kube-apiserver-arg) that could break watch serving

Example fix

// before
if err := sc.Start(ctx); err != nil {
    panic(errors.WithMessage(err, "failed to start wranger controllers"))
}

// after (tolerate apiserver warmup with a bounded retry instead of panicking)
if err := wait.PollUntilContextTimeout(ctx, 5*time.Second, 2*time.Minute, true,
    func(ctx context.Context) (bool, error) {
        return sc.Start(ctx) == nil, nil
    }); err != nil {
    panic(errors.WithMessage(err, "failed to start wrangler controllers"))
}

// pre-check apiserver readiness before re-running informer factory startup
if err := wait.PollUntilContextTimeout(ctx, time.Second, 2*time.Minute, true, func(ctx context.Context) (bool, error) {
    resp, err := localhostClient().Get("https://127.0.0.1:6443/readyz")
    if err != nil {
        return false, nil
    }
    defer resp.Body.Close()
    return resp.StatusCode == http.StatusOK, nil
}); err != nil {
    return fmt.Errorf("apiserver not ready before informer restart: %w", err)
}

When it happens

Trigger: sc.Start racing an apiserver that is restarting, overloaded, or rejecting watches; informer caches for newly registered controllers failing on RBAC/authn errors; datastore (etcd/sqlite) too slow or unavailable behind the apiserver.

Common situations: Control-plane restarts and rolling upgrades where controllers start before the apiserver is fully ready; small/single-node servers under memory or disk pressure; misconfigured admission or auth plugins causing watch failures; this panic often appears together with 226's controller panics.

Related errors

• failed to start wrangler controllers
• apiserver not ready
• failed to start %s leader controller
• no bootstrap data is available to reconcile against
• server node name not set

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/55aad027721eaf00. Report an issue: GitHub.