juanfont/headscale · error

expiring api key: %w

Error message

expiring api key: %w

What it means

Transport-level failure of 'headscale apikeys expire': client.ExpireApiKeyWithResponse returned an error before an HTTP response was received. Covers connection failures, TLS errors, and request serialization/timeout problems, not server-side rejections (those come back as non-200 and are surfaced through apiError).

Source

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

		id, prefix, err := apiKeyIDOrPrefix(cmd)
		if err != nil {
			return err
		}

		body := clientv1.ExpireApiKeyJSONRequestBody{}

		if id != 0 {
			idStr := strconv.FormatUint(id, util.Base10)
			body.Id = &idStr
		}

		if prefix != "" {
			body.Prefix = &prefix
		}

		resp, err := client.ExpireApiKeyWithResponse(ctx, body)
		if err != nil {
			return fmt.Errorf("expiring api key: %w", err)
		}

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

		return printOutput(cmd, resp.JSON200, "Key expired")
	}),
}

var deleteAPIKeyCmd = &cobra.Command{
	Use:     cmdDelete,
	Short:   "Delete an ApiKey",
	Aliases: []string{"remove", aliasDel},
	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

View on GitHub (pinned to 565fd254d0)

Solutions

1. Check server status with 'headscale health' and retry once it is up
2. Validate CLI address and CA settings against the server configuration
3. If it recurs, capture the wrapped error text — 'connection refused' vs 'context deadline exceeded' distinguishes config from timeout

if _, err := client.ExpireApiKeyWithResponse(ctx, body); err != nil {
	if isTransportError(err) { retryAfterBackoff() } else { return err }
}

When it happens

Trigger: Expiring a key while the server is down, restarting, or unreachable; context cancelled (Ctrl-C or --timeout); TLS trust misconfigured between CLI and server.

Common situations: Server restart window during automation; wrong --address in scripted environments; expired certificates on the control server.

Related errors

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

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