{"record":{"id":"fe336ed505ee395f","repo":"juanfont/headscale","slug":"server-url-cannot-use-the-same-domain-as-base-doma","errorCode":null,"errorMessage":"server_url cannot use the same domain as base_domain in a way that could make the DERP and headscale server unreachable","messagePattern":"server_url cannot use the same domain as base_domain in a way that could make the DERP and headscale server unreachable","errorType":"validation","errorClass":"errServerURLSame","httpStatus":null,"severity":"error","filePath":"hscontrol/types/config.go","lineNumber":40,"sourceCode":"\t\"tailscale.com/tailcfg\"\n\t\"tailscale.com/types/dnstype\"\n\t\"tailscale.com/util/set\"\n)\n\nconst (\n\tPKCEMethodPlain string = \"plain\"\n\tPKCEMethodS256  string = \"S256\"\n\n\tdefaultNodeStoreBatchSize = 100\n)\n\nvar (\n\terrOidcMutuallyExclusive     = errors.New(\"oidc_client_secret and oidc_client_secret_path are mutually exclusive\")\n\terrOIDCIssuerInvalid         = errors.New(\"oidc.issuer must be a valid http(s) URL\")\n\terrOIDCClientIDRequired      = errors.New(\"oidc.client_id is required when oidc.issuer is set\")\n\terrOIDCClientSecretRequired  = errors.New(\"oidc.client_secret or oidc.client_secret_path is required when oidc.issuer is set\")\n\terrServerURLSuffix           = errors.New(\"server_url cannot be part of base_domain in a way that could make the DERP and headscale server unreachable\")\n\terrServerURLSame             = errors.New(\"server_url cannot use the same domain as base_domain in a way that could make the DERP and headscale server unreachable\")\n\terrInvalidPKCEMethod         = errors.New(\"pkce.method must be either 'plain' or 'S256'\")\n\terrTrustedProxyZeroRange     = errors.New(\"0.0.0.0/0 and ::/0 are not allowed\")\n\tErrNoPrefixConfigured        = errors.New(\"no IPv4 or IPv6 prefix configured, minimum one prefix is required\")\n\tErrInvalidAllocationStrategy = errors.New(\"invalid prefix allocation strategy\")\n)\n\ntype IPAllocationStrategy string\n\nconst (\n\tIPAllocationStrategySequential IPAllocationStrategy = \"sequential\"\n\tIPAllocationStrategyRandom     IPAllocationStrategy = \"random\"\n)\n\ntype PolicyMode string\n\nconst (\n\tPolicyModeDB   = \"database\"\n\tPolicyModeFile = \"file\"","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/types/config.go#L22-L58","documentation":"errServerURLSame is an unexported config validation error in hscontrol/types/config.go:40 returned by isSafeServerURL (config.go:1339) when the server_url hostname equals base_domain exactly. Because Tailscale/MagicDNS claims the whole base_domain for the tailnet, a control plane hosted on that exact host would become unreachable from inside the tailnet.","triggerScenarios":"server_url https://example.com with dns.base_domain example.com; simpler single-domain deployments that point both settings at the same host; covered in config_test.go:532/595.","commonSituations":"Using the naked apex domain for both the headscale server and MagicDNS; misreading docs and assuming base_domain should match the server host.","solutions":["Use a distinct hostname for server_url (e.g. https://hs.example.net) not equal to base_domain","Or pick a different base_domain for MagicDNS (a subdomain dedicated to tailnet hosts)","Ensure the DERP infrastructure also lives outside base_domain","Restart and verify control-plane reachability from a joined node"],"exampleFix":"# before\nserver_url: https://example.com\ndns:\n  base_domain: example.com\n\n# after\nserver_url: https://example.com\ndns:\n  base_domain: ts.example.com","handlingStrategy":"validation","validationCode":"host := urlHostname(cfg.ServerURL)\nif host == cfg.BaseDomain {\n    return errors.New(\"server_url must not equal base_domain\")\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Never point server_url at the naked base_domain used for MagicDNS","Review dns.base_domain vs server_url in config reviews for single-domain deployments"],"tags":["headscale","config","dns","magicdns","networking"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}