juanfont/headscale · warning

only one of --id or --prefix can be provided: %w

Error message

only one of --id or --prefix can be provided: %w

What it means

Validation error from apiKeyIDOrPrefix: both --id and --prefix were supplied for an API-key subcommand (expire/delete). The API key must be addressed by exactly one identifier; providing both is ambiguous and rejected before any network call. Wraps errMissingParameter for errors.Is checks.

Source

Thrown at cmd/headscale/cli/api_key.go:124

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

		return printOutput(cmd, resp.JSON200.ApiKey, resp.JSON200.ApiKey)
	}),
}

// apiKeyIDOrPrefix reads --id and --prefix from cmd and validates that
// exactly one is provided.
func apiKeyIDOrPrefix(cmd *cobra.Command) (uint64, string, error) {
	id, _ := cmd.Flags().GetUint64("id")
	prefix, _ := cmd.Flags().GetString("prefix")

	switch {
	case id == 0 && prefix == "":
		return 0, "", fmt.Errorf("either --id or --prefix must be provided: %w", errMissingParameter)
	case id != 0 && prefix != "":
		return 0, "", fmt.Errorf("only one of --id or --prefix can be provided: %w", errMissingParameter)
	}

	return id, prefix, nil
}

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

		body := clientv1.ExpireApiKeyJSONRequestBody{}

		if id != 0 {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Remove one of the two flags — use --prefix for stable scripting, --id for interactive use
2. Check the command line construction in scripts that template both values in
3. Use 'headscale apikeys list' to decide which identifier is most convenient

Example fix

# before
headscale apikeys delete --id 3 --prefix abcdef1234

# after
headscale apikeys delete --prefix abcdef1234

if id != 0 && prefix != "" {
	return fmt.Errorf("choose exactly one of --id or --prefix")
}

When it happens

Trigger: Running 'headscale apikeys expire --id 3 --prefix abcdef1234' or the delete equivalent, where id!=0 and prefix!="" simultaneously.

Common situations: Copy-pasted command lines where a previous key's flags accumulate; shell scripts looping over both id and prefix lists; users unaware the flags are mutually exclusive.

Related errors

• either --id or --prefix must be provided: %w
• %w: api key %d not found
• parsing machine key: %w
• failed to parse ApiKey
• failed to parse oauth client secret

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