juanfont/headscale · warning

parsing machine key: %w

Error message

parsing machine key: %w

What it means

Returned by 'headscale debug create-node' when the --key flag (registration ID) cannot be parsed by types.AuthIDFromString. The registration ID has a fixed format; arbitrary strings, empty values, or wrongly copied keys fail this local validation before any server call is made.

Source

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

}

var debugCmd = &cobra.Command{
	Use:   "debug",
	Short: "debug and testing commands",
	Long:  "debug contains extra commands used for debugging and testing headscale",
}

var createNodeCmd = &cobra.Command{
	Use:   "create-node",
	Short: "Create a node that can be registered with `auth register <>` command",
	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
		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)
		}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use a registration id actually issued by the server (from a pending registration or the test harness)
2. If generating ids in tests, mirror the format accepted by types.AuthIDFromString (read its parser)
3. Drop the flag entirely if the server is meant to generate one (omit --key rather than passing a placeholder

Example fix

# before
headscale debug create-node --name n1 --user u1 --key my-custom-key

# after
headscale debug create-node --name n1 --user u1 --key "$REGISTRATION_ID"

if _, err := types.AuthIDFromString(registrationID); err != nil {
	return fmt.Errorf("--key must be a valid registration id: %w", err)
}

func validAuthID(s string) bool {
	_, err := types.AuthIDFromString(s)
	return err == nil
}

When it happens

Trigger: Passing a --key that is not a valid registration/auth ID: empty string, a machine public key (mkey:...) instead of a registration id, or a truncated/mistyped value. The check exists so the debug command fails fast without a network round trip.

Common situations: Test scripts generating their own key strings instead of using the format produced by the server; copy-paste of node keys; confusion between nodekey, machinekey, and registration id in the debug flow.

Related errors

• either --id or --prefix must be provided: %w
• only one of --id or --prefix can be provided: %w
• %w: api key %d not found
• creating node: %w
• failed to parse ApiKey

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