{"record":{"id":"c931f56e651e48bf","repo":"juanfont/headscale","slug":"oidc-client-id-is-required-when-oidc-issuer-is-set","errorCode":null,"errorMessage":"oidc.client_id is required when oidc.issuer is set","messagePattern":"oidc\\.client_id is required when oidc\\.issuer is set","errorType":"validation","errorClass":"errOIDCClientIDRequired","httpStatus":null,"severity":"error","filePath":"hscontrol/types/config.go","lineNumber":37,"sourceCode":"\t\"github.com/spf13/viper\"\n\t\"go4.org/netipx\"\n\t\"tailscale.com/net/tsaddr\"\n\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","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/types/config.go#L19-L55","documentation":"errOIDCClientIDRequired is an unexported config validation error in hscontrol/types/config.go:37 returned at config.go:388 when oidc.issuer is configured but oidc.client_id is empty. An OIDC client cannot authenticate to the IdP without its client ID, so headscale fails config validation at startup.","triggerScenarios":"Enabling the oidc section with an issuer but omitting client_id; YAML indentation placing client_id outside the oidc block; templating that leaves client_id as an empty string.","commonSituations":"First-time OIDC setup where the operator configures the issuer before creating the IdP client; env-var overrides clearing the value; config refactor breaking key nesting.","solutions":["Create an OIDC client in your IdP and set its ID under oidc.client_id","Check YAML indentation so client_id sits inside the oidc: block at the right level","Ensure no environment override sets oidc.client_id to an empty string","Restart headscale after adding the value"],"exampleFix":"# before\noidc:\n  issuer: https://idp.example.com\n\n# after\noidc:\n  issuer: https://idp.example.com\n  client_id: headscale","handlingStrategy":"validation","validationCode":"if cfg.OIDC.Issuer != \"\" && cfg.OIDC.ClientID == \"\" {\n    return errors.New(\"oidc.client_id required when issuer is set\")\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Create the IdP client first, then fill issuer + client_id + secret together","Check YAML nesting so keys land inside the oidc block"],"tags":["headscale","config","oidc","validation"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}