AdguardTeam/AdGuardHome · critical

starting tls manager: %w

Error message

starting tls manager: %w

What it means

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.

Source

Thrown at internal/home/home.go:965

		watcher = aghos.EmptyFSWatcher{}
	}

	tlsMgr, err = aghtls.NewDefaultManager(ctx, &aghtls.DefaultManagerConfig{
		ExtendedTLSConfig: confFromTLSSettings(&config.TLS),
		ServePlainDNS:     config.DNS.ServePlainDNS,
		Logger:            baseLogger.With(slogutil.KeyPrefix, "aghtls_manager"),
		Watcher:           watcher,
	})
	if err != nil {
		tlsMgrLogger.ErrorContext(ctx, "initializing", slogutil.KeyError, err)
		confModifier.Apply(ctx)
	}

	err = tlsMgr.Start(ctx)
	if err != nil {
		confModifier.Apply(ctx)

		return nil, fmt.Errorf("starting tls manager: %w", err)
	}

	sigHdlr.addTLSManager(tlsMgr)
	confModifier.setTLSManager(tlsMgr)

	return tlsMgr, nil
}

// initUpdate configures and runs update of this application.  logger and tlsMgr
// must not be nil.
func initUpdate(
	ctx context.Context,
	baseLogger *slog.Logger,
	opts options,
	tlsMgr aghtls.Manager,
	isFirstRun bool,
	workDir string,
	confPath string,

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the wrapped error cause: file-not-found means fixing cert paths in the config; parse errors mean regenerating the certificate
2. Verify file permissions: the service user must read the TLS key and cert
3. Free the configured TLS/HTTPS port (ss -ltnp / lsof -i :443) and stop conflicting services
4. If ACME-related, fix DNS/port-80 reachability for the HTTP-01 challenge

// Before starting, check cert/key files are readable and parseable:
for _, f := range []string{cfg.TLS.CertificatePath, cfg.TLS.PrivateKeyPath} {
    if _, err := os.Stat(f); err != nil { log.Fatalf("TLS file %s: %v", f, err) }
}

if err := tlsMgr.Start(ctx); err != nil {
    return fmt.Errorf("starting tls manager: %w", err) // inspect Unwrap for fs.ErrNotExist vs x509 errors
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• starting watcher: %w
• reading cert file: %w
• validating tcp ports: %w
• constructing tls config: %w
• getting embedded client subdir: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/74f978ed570378bc. Report an issue: GitHub.