{"record":{"id":"74f978ed570378bc","repo":"AdguardTeam/AdGuardHome","slug":"starting-tls-manager-w","errorCode":null,"errorMessage":"starting tls manager: %w","messagePattern":"starting tls manager: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/home/home.go","lineNumber":965,"sourceCode":"\t\twatcher = aghos.EmptyFSWatcher{}\n\t}\n\n\ttlsMgr, err = aghtls.NewDefaultManager(ctx, &aghtls.DefaultManagerConfig{\n\t\tExtendedTLSConfig: confFromTLSSettings(&config.TLS),\n\t\tServePlainDNS:     config.DNS.ServePlainDNS,\n\t\tLogger:            baseLogger.With(slogutil.KeyPrefix, \"aghtls_manager\"),\n\t\tWatcher:           watcher,\n\t})\n\tif err != nil {\n\t\ttlsMgrLogger.ErrorContext(ctx, \"initializing\", slogutil.KeyError, err)\n\t\tconfModifier.Apply(ctx)\n\t}\n\n\terr = tlsMgr.Start(ctx)\n\tif err != nil {\n\t\tconfModifier.Apply(ctx)\n\n\t\treturn nil, fmt.Errorf(\"starting tls manager: %w\", err)\n\t}\n\n\tsigHdlr.addTLSManager(tlsMgr)\n\tconfModifier.setTLSManager(tlsMgr)\n\n\treturn tlsMgr, nil\n}\n\n// initUpdate configures and runs update of this application.  logger and tlsMgr\n// must not be nil.\nfunc initUpdate(\n\tctx context.Context,\n\tbaseLogger *slog.Logger,\n\topts options,\n\ttlsMgr aghtls.Manager,\n\tisFirstRun bool,\n\tworkDir string,\n\tconfPath string,","sourceCodeStart":947,"sourceCodeEnd":983,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/home/home.go#L947-L983","documentation":"The TLS manager component of AdGuard Home failed to start. tlsMgr.Start provisions TLS certificates (loading key/cert pairs, starting ACME/Let's Encrypt management) and any failure aborts startup with this wrapped error.","triggerScenarios":"Calling newTLSManager during run when certificate files referenced by the config are unreadable, the private key fails to parse, ACME provider communication fails, or the configured HTTPS port is already in use by another process.","commonSituations":"Cert/key file paths pointing to files that were moved or permission-restricted (often after running as a different user), expired or malformed certificates, or another web server occupying port 443.","solutions":["Check the wrapped error cause: file-not-found means fixing cert paths in the config; parse errors mean regenerating the certificate","Verify file permissions: the service user must read the TLS key and cert","Free the configured TLS/HTTPS port (ss -ltnp / lsof -i :443) and stop conflicting services","If ACME-related, fix DNS/port-80 reachability for the HTTP-01 challenge"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before starting, check cert/key files are readable and parseable:\nfor _, f := range []string{cfg.TLS.CertificatePath, cfg.TLS.PrivateKeyPath} {\n    if _, err := os.Stat(f); err != nil { log.Fatalf(\"TLS file %s: %v\", f, err) }\n}","typeGuard":null,"tryCatchPattern":"if err := tlsMgr.Start(ctx); err != nil {\n    return fmt.Errorf(\"starting tls manager: %w\", err) // inspect Unwrap for fs.ErrNotExist vs x509 errors\n}","preventionTips":["Keep certificate paths stable and readable by the service user","Monitor certificate expiry and renew via the built-in ACME support","Ensure the HTTPS port is exclusive to AdGuard Home"],"tags":["go","tls","certificates","acme","startup"],"backgroundTag":"tls-certificate-load-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}