kubernetes/kops · error

error listening on %q: %w

Error message

error listening on %q: %w

What it means

NewListener calls net.Listen("tcp", listen) to bind the address the challenge gRPC server will serve on; any bind failure is wrapped with this message including the address. Typical causes are the port already in use or lacking permission to bind the address.

Source

Thrown at pkg/bootstrap/challenge_server.go:138

func (s *ChallengeListener) Stop() {
	s.grpcServer.Stop()
}

func (s *ChallengeListener) Endpoint() string {
	return s.endpoint
}

func (s *ChallengeServer) NewListener(ctx context.Context, listen string) (*ChallengeListener, error) {
	var opts []grpc.ServerOption

	opts = append(opts, grpc.Creds(credentials.NewTLS(s.tlsConfig)))
	grpcServer := grpc.NewServer(opts...)
	pb.RegisterCallbackServiceServer(grpcServer, s)

	lis, err := net.Listen("tcp", listen)
	if err != nil {
		return nil, fmt.Errorf("error listening on %q: %w", listen, err)
	}

	grpcListener := &ChallengeListener{
		server:     s,
		grpcServer: grpcServer,
		endpoint:   lis.Addr().String(),
	}

	go func() {
		klog.Infof("starting node-challenge listener on %v", lis.Addr())
		if err := grpcServer.Serve(lis); err != nil {
			lis.Close()

			klog.Warningf("error serving GRPC: %v", err)
		}
	}()

	return grpcListener, nil

View on GitHub (pinned to 4c8573c808)

Solutions

1. Check what holds the port (ss -ltnp / lsof -i :<port>) and stop it or change the listen port
2. Correct the listen address in the configuration to a valid local IP/host
3. Run with sufficient privileges or use a non-privileged port (>1024)
4. Ensure only one instance of the controller binds the port

Example fix

null

if ln, err := net.Listen("tcp", listen); err != nil {
	return fmt.Errorf("address %q unavailable before starting server: %w", listen, err)
} else { ln.Close() }

lis, err := s.NewListener(listen)
if err != nil {
	if strings.Contains(err.Error(), "error listening") && errors.Is(err, syscall.EADDRINUSE) {
		// free the port or pick an alternate port and retry
	}
	return err
}

When it happens

Trigger: Calling NewListener/Run when the configured listen address's port is occupied by another process, the address is invalid/unassigned on the host, or binding a privileged port without privileges.

Common situations: Two kops-controller replicas on the same host/port; a stale process holding the port after an upgrade; listen address typo or host networking misconfiguration; container not granted the port (non-root binding <1024).

Related errors

• error dialing target %q: %w
• error querying kubernetes version: %v
• error loading channel %q: %v
• error querying ec2 metadata service (for region): %v
• listing nodes in cluster: %v

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/36e81de840adc5c3. Report an issue: GitHub.