gravitational/teleport · error

kubernetes cluster %q is not registered or is offline

Error message

kubernetes cluster %q is not registered or is offline

What it means

Returned by KubeConnectionTester.handleUserGenCertsErr when the user's attempt to mint Kubernetes access credentials for the target cluster fails because the cluster is not registered in the Teleport cluster or its kube service is offline, so no leaf certificates can be issued for it.

Source

Thrown at lib/client/conntest/kube.go:231

	if s.cfg.TLSRoutingEnabled {
		// passing an empty string to GetKubeTLSServerName results in
		// a server name = kube.teleport.cluster.local.
		restConfig.TLSClientConfig.ServerName = client.GetKubeTLSServerName("")
		restConfig.Host = "https://" + s.webProxyAddr
	}

	client, err := kubernetes.NewForConfig(restConfig)
	return client, trace.Wrap(err)
}

// handleErrFromKube parses the errors received from the Teleport when generating
// user credentials to access the cluster.
func (s KubeConnectionTester) handleUserGenCertsErr(ctx context.Context, clusterName string, connectionDiagnosticID string, actionErr error) (types.ConnectionDiagnostic, error) {
	if trace.IsBadParameter(actionErr) {
		message := "Failed to connect to Kubernetes cluster. Ensure the cluster is registered and online."
		traceType := types.ConnectionDiagnosticTrace_CONNECTIVITY
		err := fmt.Errorf("kubernetes cluster %q is not registered or is offline", clusterName)
		return s.appendDiagnosticTrace(ctx, connectionDiagnosticID, traceType, message, err)
	} else if actionErr != nil {
		return nil, trace.Wrap(actionErr)
	}
	// success message is delayed until we reach kube proxy since the agent can be
	// registered but unreachable
	return nil, nil
}

// handleErrFromKube parses the errors received from the Teleport and marks the
// steps according to the given error.
func (s KubeConnectionTester) handleErrFromKube(ctx context.Context, clusterName string, connectionDiagnosticID string, actionErr error, namespace string) (types.ConnectionDiagnostic, error) {
	var kubeErr *kubeerrors.StatusError
	if actionErr != nil && !errors.As(actionErr, &kubeErr) {
		traceType := types.ConnectionDiagnosticTrace_UNKNOWN_ERROR
		message := fmt.Sprintf("Unknown error. %v", actionErr)
		connDiag, err := s.appendDiagnosticTrace(ctx, connectionDiagnosticID, traceType, message, actionErr)
		return connDiag, trace.Wrap(err)

View on GitHub (pinned to 1283425b60)

Solutions

1. Verify the Kubernetes cluster is registered: tsh clusters / tctl get kube_cluster
2. Check the target cluster and its kube service are online (tctl status, agent health)
3. Ensure the kube_service/discovery configuration includes this cluster
4. Retry the connection test after fixing registration

When it happens

Trigger: Thrown at lib/client/conntest/kube.go:231 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/51267e996c309625. Report an issue: GitHub.