{"record":{"id":"b6999025e26a482b","repo":"juanfont/headscale","slug":"creating-default-tls-certificates-w","errorCode":null,"errorMessage":"creating default TLS certificates: %w","messagePattern":"creating default TLS certificates: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":375,"sourceCode":"\t\tnetworks: networks,\n\n\t\tenv:              DefaultConfigEnv(),\n\t\tfilesInContainer: []fileInContainer{},\n\t\tpolicyMode:       types.PolicyModeFile,\n\t}\n\n\tfor _, opt := range opts {\n\t\topt(hsic)\n\t}\n\n\t// TLS is enabled by default for all integration tests.\n\t// Generate a self-signed certificate if TLS was not explicitly\n\t// disabled via [WithoutTLS] and no custom cert was provided\n\t// via [WithCustomTLS].\n\tif !hsic.noTLS && len(hsic.tlsCert) == 0 {\n\t\tcaCert, cert, key, err := integrationutil.CreateCertificate(hsic.hostname)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"creating default TLS certificates: %w\", err)\n\t\t}\n\n\t\thsic.tlsCACert = caCert\n\t\thsic.tlsCert = cert\n\t\thsic.tlsKey = key\n\n\t\t// Install the CA cert into the headscale container's trust\n\t\t// store so that tools like curl trust the server's own\n\t\t// certificate.\n\t\thsic.caCerts = append(hsic.caCerts, caCert)\n\t}\n\n\tlog.Println(\"NAME: \", hsic.hostname)\n\n\tportProto := fmt.Sprintf(\"%d/tcp\", hsic.port)\n\n\theadscaleBuildOptions := &dockertest.BuildOptions{\n\t\tDockerfile: IntegrationTestDockerFileName,","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L357-L393","documentation":"Returned from HeadscaleInContainer construction when integrationutil.CreateCertificate(hsic.hostname) fails. TLS is on by default for integration tests; if neither WithoutTLS nor WithCustomTLS was set, hsic generates a self-signed CA + server certificate for the container hostname. Failure means the cert-generation utility (crypto/x509 chain building, PEM encoding, key generation) errored.","triggerScenarios":"Calling hsic.NewHeadscaleInContainer(...) without WithCustomTLS/WithoutTLS on a host where the certificate helper fails: invalid/empty hostname making SANs invalid, entropy exhaustion during key generation, or a bug in the cert template.","commonSituations":"Hostname option producing an empty or illegal DNS name (WithTLSHostname with invalid chars); extremely locked-down CI runners with depleted entropy; rarely, x509 template errors after Go upgrades.","solutions":["Inspect the wrapped crypto error — most often 'x509: hostname is not a valid DNS name'","Ensure a valid container hostname (default hsic hostname or WithTLSHostname with a legal DNS label)","As a workaround, supply certs via WithCustomTLS or disable TLS via WithoutTLS","Check the CreateCertificate helper in integration/util for its hostname validation"],"exampleFix":"// workaround for an invalid custom hostname\n// before\nhsic.WithTLSHostname(\"my host\"),\n// after\nhsic.WithTLSHostname(\"my-host\"),","handlingStrategy":"validation","validationCode":"// Validate hostname before container construction (cheap guard)\nif !isValidDNSLabel(hsicHostname) { return nil, fmt.Errorf(\"invalid hostname %q\", hsicHostname) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass only legal DNS-label hostnames via WithTLSHostname","On restricted CI runners, pre-generate certs and use WithCustomTLS","Keep default hostname generation intact unless you need a custom name"],"tags":["integration-test","tls","certificate","x509"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}