juanfont/headscale · error

creating node: %w

Error message

creating node: %w

What it means

Transport error from 'headscale debug create-node': client.DebugCreateNodeWithResponse failed before an HTTP response was received. Only connectivity/serialization problems produce this; server-side rejection (bad user, duplicate name) returns a non-200 handled by apiError.

Source

Thrown at cmd/headscale/cli/debug.go:55

		user, _ := cmd.Flags().GetString("user")
		name, _ := cmd.Flags().GetString("name")
		registrationID, _ := cmd.Flags().GetString("key")

		_, err := types.AuthIDFromString(registrationID)
		if err != nil {
			return fmt.Errorf("parsing machine key: %w", err)
		}

		routes, _ := cmd.Flags().GetStringSlice("route")

		resp, err := client.DebugCreateNodeWithResponse(ctx, clientv1.DebugCreateNodeJSONRequestBody{
			Key:    &registrationID,
			Name:   &name,
			User:   &user,
			Routes: &routes,
		})
		if err != nil {
			return fmt.Errorf("creating node: %w", err)
		}

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

		return printOutput(cmd, resp.JSON200.Node, "Node created")
	}),
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Ensure the server is listening and healthy
2. Verify CLI address/TLS configuration matches the deployment
3. In test harnesses, wait for server readiness before issuing debug create-node

// harness: wait for server readiness before debug create-node
if err := waitHealthy(ctx, addr, 30*time.Second); err != nil {
	return fmt.Errorf("server not ready: %w", err)
}

if _, err := client.DebugCreateNodeWithResponse(ctx, body); err != nil {
	if isTransportError(err) { /* wait for readiness, retry once */ }
}

When it happens

Trigger: Running the debug create-node command against an unreachable server, with TLS misconfiguration, or when the request is cancelled mid-flight.

Common situations: Integration/dev harnesses invoking debug create-node before the server is fully up; CLI pointed at the wrong address after environment changes.

Related errors

• listing api keys: %w
• creating api key: %w
• expiring api key: %w
• deleting api key: %w
• registering node: %w

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