{"record":{"id":"f40fbf999aa64911","repo":"juanfont/headscale","slug":"configuration-error-w","errorCode":null,"errorMessage":"configuration error: %w","messagePattern":"configuration error: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/headscale/cli/configtest.go","lineNumber":20,"sourceCode":"\nimport (\n\t\"fmt\"\n\n\t\"github.com/spf13/cobra\"\n)\n\nfunc init() {\n\trootCmd.AddCommand(configTestCmd)\n}\n\nvar configTestCmd = &cobra.Command{\n\tUse:   \"configtest\",\n\tShort: \"Test the configuration.\",\n\tLong:  \"Run a test of the configuration and exit.\",\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t_, err := newHeadscaleServerWithConfig()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"configuration error: %w\", err)\n\t\t}\n\n\t\treturn nil\n\t},\n}\n","sourceCodeStart":2,"sourceCodeEnd":26,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/headscale/cli/configtest.go#L2-L26","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped error — it names the exact field or subsystem that failed validation","Diff your config against the packaged example config for your headscale version","Fix or remove the offending keys, validate YAML syntax, then rerun 'headscale configtest'","Add configtest to deployment pipelines so bad configs are caught before restart"],"exampleFix":"# before\nserver_url: headscale.example.com\n\n# after\nserver_url: https://headscale.example.com","handlingStrategy":"validation","validationCode":"// CI gate: run configtest before deploy\nif err := run(\"headscale\", \"-c\", cfgPath, \"configtest\"); err != nil {\n\tlog.Fatalf(\"config invalid: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := newHeadscaleServerWithConfig(); err != nil {\n\treturn fmt.Errorf(\"configuration error: %w\", err) // fail deploy, keep wrapped detail\n}","preventionTips":["Run 'headscale configtest' in CI on every config change","Diff against the versioned example config after upgrades","Lint YAML (prek/yq) before shipping"],"tags":["configuration","yaml","cli","startup","go"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}