juanfont/headscale · error

listing preauthkeys: %w

Error message

listing preauthkeys: %w

What it means

Thrown by `headscale preauthkeys list` when client.ListPreAuthKeysWithResponse() fails at the transport level — the request to the running headscale never returned. HTTP error statuses are handled separately via apiError, so this means connection-level failure.

Source

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

	createPreAuthKeyCmd.PersistentFlags().Uint64P("user", "u", 0, "User identifier (ID)")
	expirePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
	deletePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
}

var preauthkeysCmd = &cobra.Command{
	Use:     "preauthkeys",
	Short:   "Handle the preauthkeys in Headscale",
	Aliases: []string{"preauthkey", "authkey", "pre"},
}

var listPreAuthKeys = &cobra.Command{
	Use:     cmdList,
	Short:   "List all preauthkeys",
	Aliases: []string{"ls", cmdShow},
	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
		resp, err := client.ListPreAuthKeysWithResponse(ctx)
		if err != nil {
			return fmt.Errorf("listing preauthkeys: %w", err)
		}

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

		preAuthKeys := resp.JSON200.PreAuthKeys

		return printListOutput(cmd, preAuthKeys, func() error {
			rows := make([][]string, 0, len(preAuthKeys))
			for _, key := range preAuthKeys {
				expiration := ColourTime(key.Expiration)

				owner := "-"

				switch {
				case len(key.AclTags) > 0:
					owner = strings.Join(key.AclTags, "\n")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Check the service: `curl -v <server_url>/healthz`.
2. Verify HEADSCALE_ADDRESS / server_url and API key env vars used by the CLI.
3. Retry after confirming network reachability.
4. If the server is down and you only need to read keys, note there is no bypass path for preauthkeys — start the server.

func isTransportError(err error) bool {
    return err != nil && !strings.Contains(err.Error(), "api error (")
}

resp, err := client.ListPreAuthKeysWithResponse(ctx)
if err != nil && isTransportError(err) {
    // read-only call: safe to retry with backoff
}

When it happens

Trigger: headscale not running; unreachable server_url; DNS or TLS failure; connection refused/reset while listing keys.

Common situations: CLI on a workstation without network access to the server; wrong server address in env/config; service restarted mid-request.

Related errors

• creating preauthkey: %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/b12d72f0899efcf4. Report an issue: GitHub.