juanfont/headscale · error

creating api key: %w

Error message

creating api key: %w

What it means

Wrapped transport error from the 'headscale apikeys create' subcommand: the POST to /api/v1/apikey failed at the HTTP layer (client.CreateApiKeyWithResponse returned err), so no status code or body exists yet. Distinct from an HTTP-level failure, which is reported via apiError instead.

Source

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

var createAPIKeyCmd = &cobra.Command{
	Use:   "create",
	Short: "Creates a new Api key",
	Long: `
Creates a new Api key, the Api key is only visible on creation
and cannot be retrieved again.
If you lose a key, create a new one and revoke (expire) the old one.`,
	Aliases: []string{"c", cmdNew},
	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
		expiryTime, err := expirationFromFlag(cmd)
		if err != nil {
			return err
		}

		resp, err := client.CreateApiKeyWithResponse(ctx, clientv1.CreateApiKeyJSONRequestBody{
			Expiration: &expiryTime,
		})
		if err != nil {
			return fmt.Errorf("creating api key: %w", err)
		}

		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 == "":

View on GitHub (pinned to 565fd254d0)

Solutions

1. Confirm server reachability ('headscale health')
2. Fix the CLI address/TLS settings to match the server
3. Retry after the server is stable if it was restarting
4. Inspect the wrapped error for the precise transport cause (dial tcp, x509, context deadline)

if _, err := client.CreateApiKeyWithResponse(ctx, body); err != nil {
	if errors.Is(err, context.DeadlineExceeded) { return err }
	// transient dial errors: safe to retry; creation is idempotent-ish only if you de-dup by prefix afterwards
}

When it happens

Trigger: 'headscale apikeys create' with the server unreachable, a TLS handshake failure, a context cancellation/timeout, or an invalid API endpoint URL in the CLI socket configuration.

Common situations: Server not running or restarted mid-command; cert trust issues between CLI and server; expiry flag producing an invalid request body is NOT this error (that yields an HTTP 4xx via apiError) — this is purely connectivity/transport.

Related errors

• listing api keys: %w
• expiring 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/852538aebc33d61f. Report an issue: GitHub.