unable to read/write to headscale socket %q, do you have the

Error message

unable to read/write to headscale socket %q, do you have the correct permissions? %w

What it means

Error "unable to read/write to headscale socket %q, do you have the correct permissions? %w" thrown in juanfont/headscale.

Source

Thrown at cmd/headscale/cli/utils.go:205

		return nil, nil, nil, err
	}

	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via HTTPS")

	return ctx, client, cancel, nil
}

// newSocketClient builds an API client that dials the local unix socket. The
// base-URL host is irrelevant; the custom dialer routes every request to the
// socket.
func newSocketClient(socketPath string) (*clientv1.ClientWithResponses, error) {
	// Probe for a clearer permission error up front. [os.OpenFile] on a unix
	// socket returns ENXIO on Linux (expected); only permission errors are
	// actionable. The real connection goes through [net.Dial].
	socket, err := os.OpenFile(socketPath, os.O_WRONLY, SocketWritePermissions) //nolint
	if err != nil {
		if os.IsPermission(err) {
			return nil, fmt.Errorf(
				"unable to read/write to headscale socket %q, do you have the correct permissions? %w",
				socketPath,
				err,
			)
		}
	} else {
		socket.Close()
	}

	httpClient := &http.Client{
		Transport: &http.Transport{
			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
				return dialHeadscaleSocket(ctx, socketPath)
			},
		},
	}

	return clientv1.NewClientWithResponses(

View on GitHub (pinned to 565fd254d0)

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.

Example fix

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.

When it happens

Trigger: Thrown at cmd/headscale/cli/utils.go:205 when the library encounters an invalid state.

Common situations: 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.

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