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

[Bug] Headscale fails to recognize ip_prefixes in config: "no IPv4 or IPv6 prefix configured, minimum one prefix is required" on clean install (v0.25.0/v0.26.0, Docker & native) #1027

New Issue
Closed
opened 2025-12-29 02:27:48 +01:00 by adam · 1 comment
adam commented 2025-12-29 02:27:48 +01:00
Owner
Copy Link

Originally created by @slfhstr on GitHub (May 18, 2025).

Is this a support request?

  • This is not a support request

Is there an existing issue for this?

  • I have searched the existing issues

Current Behavior

Summary:
Headscale (tested v0.25.0 and v0.26.0, both Docker and native binary) fails to start with the error:

Error initializing error="loading configuration: no IPv4 or IPv6 prefix configured, minimum one prefix is required"

even though the ip_prefixes field is present, correctly formatted, and matches all official documentation and community examples.

Expected Behavior

Headscale should start and recognize the ip_prefixes field as documented.

Actual Behavior
Fails with fatal error about missing ip_prefixes, despite the field being present and correct.

Steps To Reproduce

Create a minimal config.yaml:

server_url: http://localhost:8080
listen_addr: 0.0.0.0:8080
ip_prefixes:
  - 100.64.0.0/10
  - fd7a:115c:a1e0::/48
private_key_path: /var/lib/headscale/private.key
noise:
  private_key_path: /var/lib/headscale/noise_private.key
db_type: sqlite3
db_path: /var/lib/headscale/db.sqlite

dns:
  override_local_dns: true
  nameservers:
    global:
      - 8.8.8.8
      - 1.1.1.1

Place it at /etc/headscale/config.yaml (or mount via Docker).
Run Headscale:

Docker:

docker run --rm -v "$PWD/config:/etc/headscale" ghcr.io/juanfont/headscale:0.26.0 serve --config /etc/headscale/config.yaml

Native:

./headscale_0.26.0_linux_amd64 serve --config /full/path/to/config.yaml

Observe the error:

Error initializing error="loading configuration: no IPv4 or IPv6 prefix configured, minimum one prefix is required"

What I’ve Tried :
Multiple versions: v0.25.0 and v0.26.0
Both Docker and native binary
Rewriting config file from scratch, using different editors and encodings
Validating YAML (no tabs, no BOM, no CRLF, permissions 644, owner root)
Running with and without the DNS section
Using both relative and absolute paths for config
Confirmed the config file is present and readable inside the container and on the host
No HEADSCALE_ environment variables set
Tried with minimal config (just required fields)
Tried on a VPS with 15+ other containers running fine

Environment

OS: Ubuntu 22.04 (VPS, SSDNodes)
Docker: 24.0.7
Headscale: v0.25.0 and v0.26.0 (Docker and native static binary)
Filesystem: ext4
Config location: /etc/headscale/config.yaml (mounted from ./config/config.yaml)
Other containers: 15+ running fine (Traefik, etc.)

Runtime environment

  • Headscale is behind a (reverse) proxy
  • Headscale runs in a container

Debug information

Additional Info
The config file is present and readable inside the container and on the host.
The error persists regardless of file encoding, permissions, or YAML formatting.
All official documentation and community guides have been followed exactly.
Any help or insight would be appreciated.

Originally created by @slfhstr on GitHub (May 18, 2025). ### Is this a support request? - [x] This is not a support request ### Is there an existing issue for this? - [x] I have searched the existing issues ### Current Behavior Summary: Headscale (tested v0.25.0 and v0.26.0, both Docker and native binary) fails to start with the error: ``` Error initializing error="loading configuration: no IPv4 or IPv6 prefix configured, minimum one prefix is required" ``` even though the ip_prefixes field is present, correctly formatted, and matches all official documentation and community examples. ### Expected Behavior Headscale should start and recognize the ip_prefixes field as documented. Actual Behavior Fails with fatal error about missing ip_prefixes, despite the field being present and correct. ### Steps To Reproduce Create a minimal config.yaml: ``` server_url: http://localhost:8080 listen_addr: 0.0.0.0:8080 ip_prefixes: - 100.64.0.0/10 - fd7a:115c:a1e0::/48 private_key_path: /var/lib/headscale/private.key noise: private_key_path: /var/lib/headscale/noise_private.key db_type: sqlite3 db_path: /var/lib/headscale/db.sqlite dns: override_local_dns: true nameservers: global: - 8.8.8.8 - 1.1.1.1 ``` Place it at /etc/headscale/config.yaml (or mount via Docker). Run Headscale: Docker: ``` docker run --rm -v "$PWD/config:/etc/headscale" ghcr.io/juanfont/headscale:0.26.0 serve --config /etc/headscale/config.yaml ``` Native: ``` ./headscale_0.26.0_linux_amd64 serve --config /full/path/to/config.yaml ``` Observe the error: ``` Error initializing error="loading configuration: no IPv4 or IPv6 prefix configured, minimum one prefix is required" ``` What I’ve Tried : Multiple versions: v0.25.0 and v0.26.0 Both Docker and native binary Rewriting config file from scratch, using different editors and encodings Validating YAML (no tabs, no BOM, no CRLF, permissions 644, owner root) Running with and without the DNS section Using both relative and absolute paths for config Confirmed the config file is present and readable inside the container and on the host No HEADSCALE_ environment variables set Tried with minimal config (just required fields) Tried on a VPS with 15+ other containers running fine ### Environment ```markdown OS: Ubuntu 22.04 (VPS, SSDNodes) Docker: 24.0.7 Headscale: v0.25.0 and v0.26.0 (Docker and native static binary) Filesystem: ext4 Config location: /etc/headscale/config.yaml (mounted from ./config/config.yaml) Other containers: 15+ running fine (Traefik, etc.) ``` ### Runtime environment - [x] Headscale is behind a (reverse) proxy - [x] Headscale runs in a container ### Debug information Additional Info The config file is present and readable inside the container and on the host. The error persists regardless of file encoding, permissions, or YAML formatting. All official documentation and community guides have been followed exactly. Any help or insight would be appreciated.
adam added the bug label 2025-12-29 02:27:48 +01:00
adam closed this issue 2025-12-29 02:27:48 +01:00
adam commented 2025-12-29 02:27:48 +01:00
Author
Owner
Copy Link

@slfhstr commented on GitHub (May 19, 2025):

Totally rebuilt config and docker-ccompose
Working now
I don't understand the difference
But probably ignore this.

@slfhstr commented on GitHub (May 19, 2025): Totally rebuilt config and docker-ccompose Working now I don't understand the difference But probably ignore this.
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#1027
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?