{"record":{"id":"1ce0922caea61e74","repo":"juanfont/headscale","slug":"unable-to-read-write-to-headscale-socket-q-do-yo","errorCode":null,"errorMessage":"unable to read/write to headscale socket %q, do you have the correct permissions? %w","messagePattern":"unable to read/write to headscale socket %q, do you have the correct permissions\\? %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/headscale/cli/utils.go","lineNumber":205,"sourceCode":"\t\treturn nil, nil, nil, err\n\t}\n\n\tlog.Trace().Caller().Str(zf.Address, address).Msg(\"connecting via HTTPS\")\n\n\treturn ctx, client, cancel, nil\n}\n\n// newSocketClient builds an API client that dials the local unix socket. The\n// base-URL host is irrelevant; the custom dialer routes every request to the\n// socket.\nfunc newSocketClient(socketPath string) (*clientv1.ClientWithResponses, error) {\n\t// Probe for a clearer permission error up front. [os.OpenFile] on a unix\n\t// socket returns ENXIO on Linux (expected); only permission errors are\n\t// actionable. The real connection goes through [net.Dial].\n\tsocket, err := os.OpenFile(socketPath, os.O_WRONLY, SocketWritePermissions) //nolint\n\tif err != nil {\n\t\tif os.IsPermission(err) {\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"unable to read/write to headscale socket %q, do you have the correct permissions? %w\",\n\t\t\t\tsocketPath,\n\t\t\t\terr,\n\t\t\t)\n\t\t}\n\t} else {\n\t\tsocket.Close()\n\t}\n\n\thttpClient := &http.Client{\n\t\tTransport: &http.Transport{\n\t\t\tDialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {\n\t\t\t\treturn dialHeadscaleSocket(ctx, socketPath)\n\t\t\t},\n\t\t},\n\t}\n\n\treturn clientv1.NewClientWithResponses(","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/headscale/cli/utils.go#L187-L223","documentation":"Error \"unable to read/write to headscale socket %q, do you have the correct permissions? %w\" thrown in juanfont/headscale.","triggerScenarios":"Thrown at cmd/headscale/cli/utils.go:205 when the library encounters an invalid state.","commonSituations":"The unix socket is not readable/writable by the current user. Run the CLI as the same user as the server, as root, or fix socket permissions/ownership.","solutions":["Inspect the wrapped error for the underlying cause and correct the failing condition (unable to read/write to headscale socket , do you have the correct permissions?); retry the operation after fixing the input, configuration, or environment."],"exampleFix":"Inspect the wrapped error for the underlying cause and correct the failing condition (unable to read/write to headscale socket , do you have the correct permissions?); retry the operation after fixing the input, configuration, or environment.","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}