juanfont/headscale · error

configuration error: %w

Error message

configuration error: %w

What it means

Returned by 'headscale configtest': the command tries to fully construct a headscale server from the configuration file (newHeadscaleServerWithConfig) and any setup error — unparseable YAML, invalid values, unusable database DSN, bad paths — is wrapped as 'configuration error'. It is a fail-fast gate meant to run before starting the real server.

Source

Thrown at cmd/headscale/cli/configtest.go:20

import (
	"fmt"

	"github.com/spf13/cobra"
)

func init() {
	rootCmd.AddCommand(configTestCmd)
}

var configTestCmd = &cobra.Command{
	Use:   "configtest",
	Short: "Test the configuration.",
	Long:  "Run a test of the configuration and exit.",
	RunE: func(cmd *cobra.Command, args []string) error {
		_, err := newHeadscaleServerWithConfig()
		if err != nil {
			return fmt.Errorf("configuration error: %w", err)
		}

		return nil
	},
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Read the wrapped error — it names the exact field or subsystem that failed validation
2. Diff your config against the packaged example config for your headscale version
3. Fix or remove the offending keys, validate YAML syntax, then rerun 'headscale configtest'
4. Add configtest to deployment pipelines so bad configs are caught before restart

Example fix

# before
server_url: headscale.example.com

# after
server_url: https://headscale.example.com

// CI gate: run configtest before deploy
if err := run("headscale", "-c", cfgPath, "configtest"); err != nil {
	log.Fatalf("config invalid: %v", err)
}

if _, err := newHeadscaleServerWithConfig(); err != nil {
	return fmt.Errorf("configuration error: %w", err) // fail deploy, keep wrapped detail
}

When it happens

Trigger: Running 'headscale configtest' with a config file containing invalid or mutually inconsistent settings: bad server_url, invalid TLS files, unreadable noise private key, unsupported database settings, or a config that fails strict unmarshal.

Common situations: Upgrading headscale and keeping an old config with removed/renamed keys; typos in YAML; missing certificate or key files referenced by tls_* settings; wrong permissions on /etc/headscale.

Related errors

• fatal error reading config file: %w
• must be a positive duration
• checkPeriod is only valid with action "check"
• invalid localpart format, must be localpart:*@<domain>
• users must be specified

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