What causes "shutting down watcher: %w" in AdguardTeam/AdGuardHome?

Treat as best-effort: log the error but continue process teardown if the process is exiting anyway

shutting down watcher: %w

Error message

shutting down watcher: %w

What it means

Failed to stop the fsnotify watcher during TLS manager shutdown. Returned by DefaultManager.Shutdown when watcher.Shutdown returns an error; the updates channel is still closed via defer regardless.

Source

Thrown at internal/aghtls/defaultmanager.go:272

func (mgr *DefaultManager) Start(ctx context.Context) (err error) {
	err = mgr.watcher.Start(ctx)
	if err != nil {
		return fmt.Errorf("starting watcher: %w", err)
	}

	go mgr.handleEvents(ctx)
	go mgr.handleCertFileChange(ctx)

	return nil
}

// Shutdown implements the [service.Interface] interface for *DefaultManager.
func (mgr *DefaultManager) Shutdown(ctx context.Context) (err error) {
	defer close(mgr.updates)

	err = mgr.watcher.Shutdown(ctx)
	if err != nil {
		return fmt.Errorf("shutting down watcher: %w", err)
	}

	return nil
}

// Updates implements the [Manager] interface for *DefaultManager.
func (mgr *DefaultManager) Updates(ctx context.Context) (updates <-chan UpdateSignal) {
	return mgr.updates
}

// handleEvents handles changes of the tracked files.  It is intended to be run
// in a separate goroutine.
func (mgr *DefaultManager) handleEvents(ctx context.Context) {
	defer slogutil.RecoverAndLog(ctx, mgr.logger)

	eventsCh := mgr.watcher.Events()
	if eventsCh == nil {
		mgr.logger.DebugContext(ctx, "watcher does not emit events")

View on GitHub (pinned to b41aefbe51)

Solutions

Treat as best-effort: log the error but continue process teardown if the process is exiting anyway
Ensure Shutdown is called exactly once and only after a successful Start
Check the wrapped error to confirm it is not masking a real resource leak

Defensive patterns

Strategy: try-catch

Try / catch

if err := mgr.Shutdown(ctx); err != nil {
    log.Warn("watcher shutdown issue (continuing)", "err", err)
}

Prevention

Only Shutdown managers that started successfully
Shutdown once, from a single teardown path

When it happens

Trigger: Calling Shutdown on a watcher that already failed or was never started, or when closing the inotify fd fails (rare; typically fd already closed elsewhere).

Common situations: Double-shutdown; shutting down a manager whose Start failed earlier; racing a Shutdown with a concurrently failing watcher goroutine.

Related errors

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