juanfont/headscale · error

registering node: %w

Error message

registering node: %w

What it means

Transport error from 'headscale nodes register' (authRegisterCmd): client.AuthRegisterWithResponse failed before receiving an HTTP response. This is the CLI path that approves a pending registration and assigns it to a user; failure here means connectivity to the server, not registration semantics.

Source

Thrown at cmd/headscale/cli/auth.go:46

var authCmd = &cobra.Command{
	Use:   "auth",
	Short: "Manage node authentication and approval",
}

var authRegisterCmd = &cobra.Command{
	Use:   "register",
	Short: "Register a node to your network",
	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
		user, _ := cmd.Flags().GetString("user")
		authID, _ := cmd.Flags().GetString("auth-id")

		resp, err := client.AuthRegisterWithResponse(ctx, clientv1.AuthRegisterJSONRequestBody{
			AuthId: &authID,
			User:   &user,
		})
		if err != nil {
			return fmt.Errorf("registering node: %w", err)
		}

		if resp.StatusCode() != http.StatusOK {
			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
		}

		node := resp.JSON200.Node

		return printOutput(
			cmd,
			node,
			fmt.Sprintf("Node %s registered", node.GivenName),
		)
	}),
}

var authApproveCmd = &cobra.Command{
	Use:   "approve",

View on GitHub (pinned to 565fd254d0)

Solutions

1. Confirm the server is running and reachable ('headscale health')
2. Check CLI address and CA configuration
3. Retry the register once the server is stable — registration requests are idempotent per pending auth key

if _, err := client.AuthRegisterWithResponse(ctx, body); err != nil {
	if isTransportError(err) { /* reconnect and retry; registration stays pending server-side */ }
}

When it happens

Trigger: 'headscale nodes register --user X' with the server unreachable, TLS misconfigured, or the command cancelled before the request completed.

Common situations: Registering a node while headscale is restarting; CLI socket/address config wrong after a config change; CI environments without a reachable server.

Related errors

• listing api keys: %w
• creating api key: %w
• expiring api key: %w
• deleting api key: %w
• approving auth request: %w

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/37a137cf8376e3b6. Report an issue: GitHub.