AdguardTeam/AdGuardHome · error

shutdown failed: %w

Error message

shutdown failed: %w

What it means

Refresh performs a full stop-then-start reconfiguration; this wraps a failure during the Shutdown phase of that cycle (see 397/398). The new configuration is never started when this returns.

Source

Thrown at internal/next/cmd/service.go:149

	if err != nil {
		s.logger.ErrorContext(ctx, "removing pidfile", slogutil.KeyError, err)

		return
	}

	s.logger.DebugContext(ctx, "removed pidfile", "file", s.pidFilePath)
}

// type check
var _ service.Refresher = (*serviceMgr)(nil)

// Refresh implements the [service.Refresher] interface for *serviceMgr.
func (s *serviceMgr) Refresh(ctx context.Context) (err error) {
	s.logger.InfoContext(ctx, "reconfiguring started")

	err = s.Shutdown(ctx)
	if err != nil {
		return fmt.Errorf("shutdown failed: %w", err)
	}

	// TODO(a.garipov):  This is a very rough way to do it.  Some services can
	// be reconfigured without the full shutdown, and the error handling is
	// currently not the best.

	ctx, cancel := context.WithTimeout(ctx, defaultTimeoutStart)
	defer cancel()

	err = s.updConfMgr(ctx)
	if err != nil {
		return fmt.Errorf("updating configuration manager: %w", err)
	}

	err = s.Start(ctx)
	if err != nil {
		return fmt.Errorf("restarting services: %w", err)
	}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Inspect the wrapped error to see whether web or DNS shutdown failed and why
2. Retry the refresh once load subsides
3. Lengthen shutdown deadlines in the service configuration

err := s.Refresh(ctx)
if err != nil && strings.Contains(err.Error(), "shutdown failed") {
	ctx2, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	err = s.Refresh(ctx2)
}

When it happens

Trigger: s.Shutdown(ctx) returns a joined web/DNS shutdown error; the service remains stopped and the error propagates to the caller of Refresh.

Common situations: Reconfigure under load with too-short timeouts; shutdown races with in-flight requests during SIGHUP/config-change handling.

Related errors

• duplicated values: %v
• unmarshalling json data into aghalg.NullBool: bad value %q
• json duration is nil
• refreshing: %w
• shutting down watcher: %w

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