juanfont/headscale · error

creating preauthkey: %w

Error message

creating preauthkey: %w

What it means

Thrown by `headscale preauthkeys create` when client.CreatePreAuthKeyWithResponse() fails at the transport level before a response arrives. The request body (user, reusable, ephemeral, aclTags, expiration) was assembled successfully; the HTTP call itself failed.

Source

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

		expiryTime, err := expirationFromFlag(cmd)
		if err != nil {
			return err
		}

		userStr := strconv.FormatUint(user, util.Base10)

		request := clientv1.CreatePreAuthKeyJSONRequestBody{
			User:       &userStr,
			Reusable:   &reusable,
			Ephemeral:  &ephemeral,
			AclTags:    &tags,
			Expiration: &expiryTime,
		}

		resp, err := client.CreatePreAuthKeyWithResponse(ctx, request)
		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)
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify reachability of the API endpoint with curl.
2. Retry the command — creates are safe to retry since failure means nothing was created.
3. Confirm server_url and the API key in the CLI configuration.
4. Check reverse proxy timeouts if the server is behind one.

resp, err := client.CreatePreAuthKeyWithResponse(ctx, request)
if err != nil && isTransportError(err) {
    // create is side-effectful: before retrying, list keys to confirm none was created, then retry once
}

When it happens

Trigger: Server unreachable, DNS failure, TLS mismatch, connection reset while posting the create request.

Common situations: Running the create command right as headscale restarts; API key env var pointing at a different server; firewall dropping POST bodies.

Related errors

• listing preauthkeys: %w
• expiring preauthkey: %w
• deleting preauthkey: %w
• loading ACL policy: %w
• health check timed out

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