{"record":{"id":"b12d72f0899efcf4","repo":"juanfont/headscale","slug":"listing-preauthkeys-w","errorCode":null,"errorMessage":"listing preauthkeys: %w","messagePattern":"listing preauthkeys: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/headscale/cli/preauthkeys.go","lineNumber":51,"sourceCode":"\tcreatePreAuthKeyCmd.PersistentFlags().Uint64P(\"user\", \"u\", 0, \"User identifier (ID)\")\n\texpirePreAuthKeyCmd.PersistentFlags().Uint64P(\"id\", \"i\", 0, \"Authkey ID\")\n\tdeletePreAuthKeyCmd.PersistentFlags().Uint64P(\"id\", \"i\", 0, \"Authkey ID\")\n}\n\nvar preauthkeysCmd = &cobra.Command{\n\tUse:     \"preauthkeys\",\n\tShort:   \"Handle the preauthkeys in Headscale\",\n\tAliases: []string{\"preauthkey\", \"authkey\", \"pre\"},\n}\n\nvar listPreAuthKeys = &cobra.Command{\n\tUse:     cmdList,\n\tShort:   \"List all preauthkeys\",\n\tAliases: []string{\"ls\", cmdShow},\n\tRunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {\n\t\tresp, err := client.ListPreAuthKeysWithResponse(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"listing preauthkeys: %w\", err)\n\t\t}\n\n\t\tif resp.StatusCode() != http.StatusOK {\n\t\t\treturn apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)\n\t\t}\n\n\t\tpreAuthKeys := resp.JSON200.PreAuthKeys\n\n\t\treturn printListOutput(cmd, preAuthKeys, func() error {\n\t\t\trows := make([][]string, 0, len(preAuthKeys))\n\t\t\tfor _, key := range preAuthKeys {\n\t\t\t\texpiration := ColourTime(key.Expiration)\n\n\t\t\t\towner := \"-\"\n\n\t\t\t\tswitch {\n\t\t\t\tcase len(key.AclTags) > 0:\n\t\t\t\t\towner = strings.Join(key.AclTags, \"\\n\")","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/headscale/cli/preauthkeys.go#L33-L69","documentation":"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.","triggerScenarios":"headscale not running; unreachable server_url; DNS or TLS failure; connection refused/reset while listing keys.","commonSituations":"CLI on a workstation without network access to the server; wrong server address in env/config; service restarted mid-request.","solutions":["Check the service: `curl -v <server_url>/healthz`.","Verify HEADSCALE_ADDRESS / server_url and API key env vars used by the CLI.","Retry after confirming network reachability.","If the server is down and you only need to read keys, note there is no bypass path for preauthkeys — start the server."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"func isTransportError(err error) bool {\n    return err != nil && !strings.Contains(err.Error(), \"api error (\")\n}","tryCatchPattern":"resp, err := client.ListPreAuthKeysWithResponse(ctx)\nif err != nil && isTransportError(err) {\n    // read-only call: safe to retry with backoff\n}","preventionTips":["Verify server health before scripting CLI listing commands.","Cache/record key ids at creation time to reduce dependence on listing.","Keep API key and server URL in one sourced env file."],"tags":["network","http","cli","preauthkeys"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}