juanfont/headscale · error · errMissingParameter

missing --id parameter: %w

Error message

missing --id parameter: %w

What it means

Thrown by preAuthKeyID() when the --id flag is absent or zero for preauthkey expire/delete commands. It wraps the sentinel errMissingParameter. Note it is a flag-presence check: id 0 is treated as missing because headscale ids start at 1.

Source

Thrown at cmd/headscale/cli/preauthkeys.go:144

		if err != nil {
			return fmt.Errorf("creating preauthkey: %w", err)
		}

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

		preAuthKey := resp.JSON200.PreAuthKey

		return printOutput(cmd, preAuthKey, preAuthKey.Key)
	}),
}

// preAuthKeyID reads the required --id flag for preauthkey commands.
func preAuthKeyID(cmd *cobra.Command) (uint64, error) {
	id, _ := cmd.Flags().GetUint64("id")
	if id == 0 {
		return 0, fmt.Errorf("missing --id parameter: %w", errMissingParameter)
	}

	return id, nil
}

var expirePreAuthKeyCmd = &cobra.Command{
	Use:     cmdExpire,
	Short:   "Expire a preauthkey",
	Aliases: []string{"revoke", aliasExp, "e"},
	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
		id, err := preAuthKeyID(cmd)
		if err != nil {
			return err
		}

		idStr := strconv.FormatUint(id, util.Base10)

		resp, err := client.ExpirePreAuthKeyWithResponse(ctx, clientv1.ExpirePreAuthKeyJSONRequestBody{

View on GitHub (pinned to 565fd254d0)

Solutions

1. Find the key's id first: `headscale preauthkeys list` (id column).
2. Pass it explicitly: `headscale preauthkeys expire --id 42`.
3. In scripts, fail early if the id variable is empty before invoking the CLI.

Example fix

# before
headscale preauthkeys expire

# after
headscale preauthkeys expire --id 42

func requireFlag(cmd *cobra.Command, name string) (uint64, error) {
    id, _ := cmd.Flags().GetUint64(name)
    if id == 0 {
        return 0, fmt.Errorf("--%s is required (see `preauthkeys list`)", name)
    }
    return id, nil
}

id, err := preAuthKeyID(cmd)
if err != nil {
    // usage error: print id list hint, exit non-zero; never guess an id
    return err
}

When it happens

Trigger: `headscale preauthkeys expire` without --id, or with --id 0. Affects both expire and delete subcommands.

Common situations: Copy-pasting from docs that omit the flag; scripting where the id variable is empty and formats to 0.

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
• parsing machine key: %w
• parsing policy file: %w

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