AdguardTeam/AdGuardHome · error

initializing service: %w

Error message

initializing service: %w

What it means

handleRun could not create the system service object via service.New (kardianos/service). This validates the service configuration (name, executable path, arguments) and platform service integration before running.

Source

Thrown at internal/home/service.go:116

	if err != nil {
		return fmt.Errorf("getting current directory: %w", err)
	}

	args := optsToArgs(opts)
	baseLogger.DebugContext(ctx, "using", "args", args)

	svcConfig := &service.Config{
		Name:             serviceName,
		DisplayName:      serviceDisplayName,
		Description:      serviceDescription,
		WorkingDirectory: pwd,
		Arguments:        args,
	}
	ossvc.ConfigureServiceOptions(svcConfig, p.clock.Now(), version.Full())

	s, err := service.New(p, svcConfig)
	if err != nil {
		return fmt.Errorf("initializing service: %w", err)
	}

	return s.Run()
}

// restartService restarts the service.  It returns error if the service is not
// running.  l must not be nil.
func restartService(ctx context.Context, baseLogger *slog.Logger) (err error) {
	svcMgr, err := ossvc.NewManager(ctx, &ossvc.ManagerConfig{
		Clock:              timeutil.SystemClock{},
		Logger:             baseLogger.With(slogutil.KeyPrefix, svcLogPrefix),
		CommandConstructor: executil.SystemCommandConstructor{},
	})
	if err != nil {
		return fmt.Errorf("initializing service manager: %w", err)
	}

	act := &ossvc.ActionRestart{

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the inner error for the platform-specific cause
2. Run under a real init system or in the foreground (./AdGuardHome) in containers
3. Ensure the executable path in the service config exists and is executable

// Verify the executable exists before service.New:
if _, err := os.Stat(os.Args[0]); err != nil { return err }

if err := handleRun(...); err != nil {
    if strings.Contains(err.Error(), "initializing service") {
        // likely unsupported platform or bad exec path; run in foreground instead
    }
}

When it happens

Trigger: Invoking the 'run' service action when the service Config is invalid for the platform — bad executable path, unsupported service system, or missing permissions to interface with the system service manager.

Common situations: Running the binary in an environment without systemd/sysv/launchd (minimal containers), a renamed/moved executable, or restricted environments like some NAS sandboxing.

Related errors

• restarting service: %w
• action %q: %w
• getting current directory: %w
• initializing service manager: %w
• %w: %q

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