starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-12 04:10:32 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

fail to run headscale serve #561

New Issue
Closed
opened 2025-12-29 02:20:20 +01:00 by adam · 12 comments
adam commented 2025-12-29 02:20:20 +01:00
Owner
Copy Link

Originally created by @Micraow on GitHub (Sep 30, 2023).

Bug description

After following the brief installation guide step by step, I came to systemctl status headscale

Unfortunately, it fails. I retried and checked my conf, but it still exist:

图片

I tried headscale serve as root, but it shows:

2023-09-30T11:37:41+08:00 INF ../home/runner/work/headscale/headscale/hscontrol/derp_server.go:92 > DERP region: {RegionID:999 RegionCode:headscale RegionName:Headscale Embedded DERP Avoid:false Nodes:[0xc00008b0e0]}
2023-09-30T11:37:42+08:00 INF STUN server started at [::]:3479
2023-09-30T11:37:42+08:00 INF Setting up a DERPMap update worker frequency=86400000
2023-09-30T11:37:42+08:00 FTL ../home/runner/work/headscale/headscale/cmd/headscale/cli/server.go:26 > Error starting server error="failed to set up gRPC socket: listen unix /var/run/headscale/headscale.sock: bind: no such file or directory"

I hope you can help me with it. Thanks!

Environment

  • OS: Debian GNU/Linux 11 (bullseye)
  • Headscale version: 0.23.0-alpha1
  • Tailscale version:

To Reproduce

follow the guide at: https://headscale.net/running-headscale-linux/#installation

Originally created by @Micraow on GitHub (Sep 30, 2023). <!-- Before posting a bug report, discuss the behaviour you are expecting with the Discord community to make sure that it is truly a bug. The issue tracker is not the place to ask for support or how to set up Headscale. Bug reports without the sufficient information will be closed. Headscale is a multinational community across the globe. Our language is English. All bug reports needs to be in English. --> ## Bug description <!-- A clear and concise description of what the bug is. Describe the expected bahavior and how it is currently different. If you are unsure if it is a bug, consider discussing it on our Discord server first. --> After following the brief installation guide step by step, I came to `systemctl status headscale` Unfortunately, it fails. I retried and checked my conf, but it still exist: ![图片](https://github.com/juanfont/headscale/assets/48644801/e1f9ef10-9053-459c-9eb3-e5eab3be6745) I tried `headscale serve` as **root**, but it shows: ```bash 2023-09-30T11:37:41+08:00 INF ../home/runner/work/headscale/headscale/hscontrol/derp_server.go:92 > DERP region: {RegionID:999 RegionCode:headscale RegionName:Headscale Embedded DERP Avoid:false Nodes:[0xc00008b0e0]} 2023-09-30T11:37:42+08:00 INF STUN server started at [::]:3479 2023-09-30T11:37:42+08:00 INF Setting up a DERPMap update worker frequency=86400000 2023-09-30T11:37:42+08:00 FTL ../home/runner/work/headscale/headscale/cmd/headscale/cli/server.go:26 > Error starting server error="failed to set up gRPC socket: listen unix /var/run/headscale/headscale.sock: bind: no such file or directory" ``` I hope you can help me with it. Thanks! ## Environment <!-- Please add relevant information about your system. For example: - Version of headscale used - Version of tailscale client - OS (e.g. Linux, Mac, Cygwin, WSL, etc.) and version - Kernel version - The relevant config parameters you used - Log output --> - OS: Debian GNU/Linux 11 (bullseye) - Headscale version: 0.23.0-alpha1 - Tailscale version: <!-- We do not support running Headscale in a container nor behind a (reverse) proxy. If either of these are true for your environment, ask the community in Discord instead of filing a bug report. --> ## To Reproduce <!-- Steps to reproduce the behavior. --> follow the guide at: https://headscale.net/running-headscale-linux/#installation
adam added the bug label 2025-12-29 02:20:20 +01:00
adam closed this issue 2025-12-29 02:20:20 +01:00
adam commented 2025-12-29 02:20:20 +01:00
Author
Owner
Copy Link

@zacred0rryn commented on GitHub (Sep 30, 2023):

I just encountered the exact same failure as you on ubuntu20.04 with v0.22.3, and I tried mkdir -p /var/run/headscale && touch /var/run/headscale/headscale.sock as root which didn't help since the /var/run/headscale directory disappeared immediately.

@zacred0rryn commented on GitHub (Sep 30, 2023): I just encountered the exact same failure as you on ubuntu20.04 with v0.22.3, and I tried `mkdir -p /var/run/headscale && touch /var/run/headscale/headscale.sock` as root which didn't help since the `/var/run/headscale` directory disappeared immediately.
adam commented 2025-12-29 02:20:21 +01:00
Author
Owner
Copy Link

@Micraow commented on GitHub (Sep 30, 2023):

I just encountered the exact same failure as you on ubuntu20.04 with v0.22.3, and I tried mkdir -p /var/run/headscale && touch /var/run/headscale/headscale.sock as root which didn't help since the /var/run/headscale directory disappeared immediately.

Yes! I also tried this and the folder disappeared immediately. I thought it was my own fault before.

@Micraow commented on GitHub (Sep 30, 2023): > I just encountered the exact same failure as you on ubuntu20.04 with v0.22.3, and I tried `mkdir -p /var/run/headscale && touch /var/run/headscale/headscale.sock` as root which didn't help since the `/var/run/headscale` directory disappeared immediately. Yes! I also tried this and the folder disappeared immediately. I thought it was my own fault before.
adam commented 2025-12-29 02:20:21 +01:00
Author
Owner
Copy Link

@Micraow commented on GitHub (Sep 30, 2023):

The docker version outputs this:

2023-09-30T07:57:25Z INF No private key file at path, creating... path=/var/lib/headscale/private.key
2023-09-30T07:57:25Z FTL go/src/headscale/cmd/headscale/cli/server.go:21 > Error initializing error="failed to read or create private key: failed to save private key to disk: open /var/lib/headscale/private.key: no such file or directory"

@Micraow commented on GitHub (Sep 30, 2023): The docker version outputs this: 2023-09-30T07:57:25Z INF No private key file at path, creating... path=/var/lib/headscale/private.key 2023-09-30T07:57:25Z FTL go/src/headscale/cmd/headscale/cli/server.go:21 > Error initializing error="failed to read or create private key: failed to save private key to disk: open /var/lib/headscale/private.key: no such file or directory"
adam commented 2025-12-29 02:20:21 +01:00
Author
Owner
Copy Link

@zacred0rryn commented on GitHub (Sep 30, 2023):

I've solved the problem on my machine by deleting all related stuff first:

# apt remove headscale

# rm -rf /etc/headscale && rm-rf /var/lib/headscale

# usermod -g root headscale && groupdel headscale && userdel headscale

Then redo the installation and get config.yaml set (I kept unix_socket unchanged from the example config), and the service starts up successfully with no error after reboot either.

I don't know why this worked for me. It just did.

@zacred0rryn commented on GitHub (Sep 30, 2023): I've solved the problem on my machine by deleting all related stuff first: ```bash # apt remove headscale # rm -rf /etc/headscale && rm-rf /var/lib/headscale # usermod -g root headscale && groupdel headscale && userdel headscale ``` Then redo the installation and get `config.yaml` set (I kept `unix_socket` unchanged from the example config), and the service starts up successfully with no error after reboot either. I don't know why this worked for me. It just did.
adam commented 2025-12-29 02:20:21 +01:00
Author
Owner
Copy Link

@Micraow commented on GitHub (Sep 30, 2023):

Oops!
It doesn't work for me.

在 2023-09-30 17:26:36，"桜戸りん" @.***> 写道：

I've solved the problem on my machine by deleting all related stuff first:

apt remove headscale# rm -rf /etc/headscale && rm-rf /var/lib/headscale# usermod -g root headscale && groupdel headscale && userdel headscale

Then redo the installation and get config.yaml set (I kept unix_socket unchanged from the example config), and the service starts up successfully with no error after reboot either.

I don't know why this worked for me. It just did.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you authored the thread.Message ID: @.***>

@Micraow commented on GitHub (Sep 30, 2023): Oops! It doesn't work for me. 在 2023-09-30 17:26:36，"桜戸りん" ***@***.***> 写道： I've solved the problem on my machine by deleting all related stuff first: # apt remove headscale# rm -rf /etc/headscale && rm-rf /var/lib/headscale# usermod -g root headscale && groupdel headscale && userdel headscale Then redo the installation and get config.yaml set (I kept unix_socket unchanged from the example config), and the service starts up successfully with no error after reboot either. I don't know why this worked for me. It just did. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: ***@***.***>
adam commented 2025-12-29 02:20:22 +01:00
Author
Owner
Copy Link

@XiaowenHu96 commented on GitHub (Oct 17, 2023):

I encountered the same issue on the same version of the OS, and it was resolved simply by cleaning up the directories and reinstalling. This issue might be related to #1417.

Looking at the postinstall.sh script, I couldn't find anything suspicious. Permissions appear to be set correctly, but I should note that I'm not experienced with Debian packaging.

Could you please share the output from the system journal using this command: journalctl -u headscale?

@XiaowenHu96 commented on GitHub (Oct 17, 2023): I encountered the same issue on the same version of the OS, and it was resolved simply by cleaning up the directories and reinstalling. This issue might be related to #1417. Looking at the `postinstall.sh` script, I couldn't find anything suspicious. Permissions appear to be set correctly, but I should note that I'm not experienced with Debian packaging. Could you please share the output from the system journal using this command: `journalctl -u headscale`?
adam commented 2025-12-29 02:20:22 +01:00
Author
Owner
Copy Link

@myltw commented on GitHub (Dec 1, 2023):

The docker version outputs this:

2023-09-30T07:57:25Z INF No private key file at path, creating... path=/var/lib/headscale/private.key 2023-09-30T07:57:25Z FTL go/src/headscale/cmd/headscale/cli/server.go:21 > Error initializing error="failed to read or create private key: failed to save private key to disk: open /var/lib/headscale/private.key: no such file or directory"

@myltw commented on GitHub (Dec 1, 2023): > The docker version outputs this: > > 2023-09-30T07:57:25Z INF No private key file at path, creating... path=/var/lib/headscale/private.key 2023-09-30T07:57:25Z FTL go/src/headscale/cmd/headscale/cli/server.go:21 > Error initializing error="failed to read or create private key: failed to save private key to disk: open /var/lib/headscale/private.key: no such file or directory"
adam commented 2025-12-29 02:20:22 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Dec 10, 2023):

Please use discord for support requests.

@kradalby commented on GitHub (Dec 10, 2023): Please use discord for support requests.
adam commented 2025-12-29 02:20:23 +01:00
Author
Owner
Copy Link

@samdelong commented on GitHub (Jan 24, 2024):

I was able to work around this by appending the mkdir command before starting headscale as such sudo mkdir /var/run/headscale && sudo headscale serve

@samdelong commented on GitHub (Jan 24, 2024): I was able to work around this by appending the mkdir command before starting headscale as such ```sudo mkdir /var/run/headscale && sudo headscale serve```
adam commented 2025-12-29 02:20:23 +01:00
Author
Owner
Copy Link

@luckylinux commented on GitHub (Feb 25, 2024):

Not the prettiest solution when using Docker/Podman, but you could just add a volume mount to /var/run/headscale.

In my case I created a folder in /home/podman/run/headscale (my podman running user is podman):

mkdir -p ~/run/headscale

Example compose.yml:

version: '3.9'
networks:
  headscale:
    external: true

services:
  headscale:
    image: headscale/headscale:latest-alpine
    pull_policy: always
    container_name: headscale
    hostname: headscale.MYDOMAIN.TLD
    domainname: MYDOMAIN.TLD
    restart: unless-stopped
    command: headscale serve
    volumes:
      - ~/config/headscale:/etc/headscale
      - ~/data/headscale:/var/lib/headscale
      - ~/run/headscale:/var/run/headscale
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.headscale-rtr.rule=PathPrefix(`/`) && Host(`headscale.MYDOMAIN.TLD`)"

      - "traefik.http.services.headscale-svc.loadbalancer.server.port=8080"
    depends_on:
      - traefik
@luckylinux commented on GitHub (Feb 25, 2024): Not the prettiest solution when using Docker/Podman, but you could just add a volume mount to /var/run/headscale. In my case I created a folder in /home/podman/run/headscale (my podman running user is `podman`): ``` mkdir -p ~/run/headscale ``` Example `compose.yml`: ``` version: '3.9' networks: headscale: external: true services: headscale: image: headscale/headscale:latest-alpine pull_policy: always container_name: headscale hostname: headscale.MYDOMAIN.TLD domainname: MYDOMAIN.TLD restart: unless-stopped command: headscale serve volumes: - ~/config/headscale:/etc/headscale - ~/data/headscale:/var/lib/headscale - ~/run/headscale:/var/run/headscale labels: - "traefik.enable=true" - "traefik.http.routers.headscale-rtr.rule=PathPrefix(`/`) && Host(`headscale.MYDOMAIN.TLD`)" - "traefik.http.services.headscale-svc.loadbalancer.server.port=8080" depends_on: - traefik ```
adam commented 2025-12-29 02:20:23 +01:00
Author
Owner
Copy Link

@W1BTR commented on GitHub (Aug 6, 2024):

Also having this issue when running through docker using the updated config. I plan to run behind a reverse proxy called caddy.

headscale fails to run with the error:

Error starting server error="failed to set up gRPC socket: listen unix /var/run/headscale/headscale.sock: bind: no such file or directory"

I tried pruning the container and removing the config but still have this issue. @luckylinux what exactly did you put in /run/headscale? I dont have anything set for /var/run/headscale in my docker-compose.

@W1BTR commented on GitHub (Aug 6, 2024): Also having this issue when running through docker using the updated config. I plan to run behind a reverse proxy called caddy. headscale fails to run with the error: ` Error starting server error="failed to set up gRPC socket: listen unix /var/run/headscale/headscale.sock: bind: no such file or directory"` I tried pruning the container and removing the config but still have this issue. @luckylinux what exactly did you put in /run/headscale? I dont have anything set for /var/run/headscale in my docker-compose.
adam commented 2025-12-29 02:20:23 +01:00
Author
Owner
Copy Link

@luckylinux commented on GitHub (Aug 7, 2024):

@W1BTR: it was ~/run/headscale AKA /home/<myuser>/run/headscale. Pretty sure you don't have to put anything, just create the folder and mount, so that Headscale can create Files (which apparently did NOT work unless I did that - weird).

Anyway since I got the "Headscale is no supported yada yada" Talk when discussing Issues with the Tailscale Client on the Tailscale Issue Tracker (especially related to DNS Issues), I was trying to move on to netbird instead but faced several Issues related to SSO (both Keycloak and Authentik). So right now I'm stuck with nothing working to be honest ...

@luckylinux commented on GitHub (Aug 7, 2024): @W1BTR: it was `~/run/headscale` AKA `/home/<myuser>/run/headscale`. Pretty sure you don't have to put anything, just create the folder and mount, so that Headscale can create Files (which apparently did NOT work unless I did that - weird). Anyway since I got the "Headscale is no supported yada yada" Talk when discussing Issues with the Tailscale Client on the Tailscale Issue Tracker (especially related to DNS Issues), I was trying to move on to `netbird` instead but faced several Issues related to SSO (both Keycloak and Authentik). So right now I'm stuck with nothing working to be honest ...
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#561
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?