cilium/cilium · error

failed to wait for endpoint restorer promise: %w

Error message

failed to wait for endpoint restorer promise: %w

What it means

createHostEndpoint must wait for the endpoint restorer promise (resolved once endpoint restoration completes) before creating the host endpoint. If the promise's Await(ctx) fails — most commonly because the context is cancelled/times out before restoration resolves — this error wraps the cause. The host endpoint is then not created, breaking local connectivity setup.

Source

Thrown at daemon/infraendpoints/host_endpoint.go:54

	endpointRestorePromise promise.Promise[endpointstate.Restorer]
}

func registerHostEndpoint(params hostEndpointParams) {
	creator := &hostEndpointCreator{
		logger:                 params.Logger,
		endpointCreator:        params.EndpointCreator,
		endpointManager:        params.EndpointManager,
		endpointRestorePromise: params.EndpointRestorePromise,
	}

	params.JobGroup.Add(job.OneShot("init-host-endpoint", creator.createHostEndpoint, job.WithShutdown()))
}

func (c *hostEndpointCreator) createHostEndpoint(ctx context.Context, health cell.Health) error {
	health.OK("Wait for endpoint restoration")
	r, err := c.endpointRestorePromise.Await(ctx)
	if err != nil {
		return fmt.Errorf("failed to wait for endpoint restorer promise: %w", err)
	}

	if err := r.WaitForEndpointRestoreWithoutRegeneration(ctx); err != nil {
		return fmt.Errorf("failed to wait for endpoint restoration: %w", err)
	}

	health.OK("Start initialization")

	if c.endpointManager.HostEndpointExists() {
		c.logger.Info("Initializing labels on existing host endpoint")
		c.endpointManager.InitHostEndpointLabels(ctx)
		return nil
	}

	c.logger.Info("Creating host endpoint")
	if err := c.endpointCreator.AddHostEndpoint(ctx); err != nil {
		return fmt.Errorf("unable to create host endpoint: %w", err)
	}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check why endpoint restoration did not complete (look for earlier 'endpoint restore'/'regeneration' errors in agent logs)
2. Increase startup/lifecycle timeouts if restore is merely slow (large endpoint count)
3. Restart the agent; if restore persistently hangs, inspect bpf maps/state and consider cilium-dbg endpoint list diagnostics
4. Verify hive/cell wiring provides the endpointRestorePromise (a version mismatch can leave it never resolved)

select {
case <-time.After(restoreTimeout):
	return errors.New("endpoint restoration did not complete within timeout")
case <-ctx.Done():
	// proceed to Await and surface its error
}

r, err := c.endpointRestorePromise.Await(ctx)
if err != nil {
	if errors.Is(err, context.Canceled) {
		return fmt.Errorf("host endpoint creation cancelled during shutdown: %w", err)
	}
	return fmt.Errorf("failed to wait for endpoint restorer promise: %w", err)
}

When it happens

Trigger: c.endpointRestorePromise.Await(ctx) returns an error when ctx is done (agent shutdown, hive lifecycle cancellation, or restore never completing) before WaitForEndpointRestoreWithoutRegeneration is even reached.

Common situations: Endpoint restoration hanging due to stuck regeneration or bpf map issues, causing the await to time out; agent stopping during startup; deadlock in the restore dependency chain after upgrades.

Related errors

• failed to wait for initial IPCache revision: %w
• remote cluster configuration required but not found
• timed out waiting for ENIs to be attached
• owner does not exist
• i/o timeout

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/c46135d5cf7c512e. Report an issue: GitHub.