{"record":{"id":"b4e0d21170be396d","repo":"AdguardTeam/AdGuardHome","slug":"installing-service-w","errorCode":null,"errorMessage":"installing service: %w","messagePattern":"installing service: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/home/service.go","lineNumber":335,"sourceCode":"\t\treturn fmt.Errorf(\"getting current directory: %w\", err)\n\t}\n\n\trunOpts := opts\n\trunOpts.serviceControlAction = \"run\"\n\n\targs := optsToArgs(runOpts)\n\tl.DebugContext(ctx, \"using\", \"args\", args)\n\n\terr = mgr.Perform(ctx, &ossvc.ActionInstall{\n\t\tServiceName:      serviceName,\n\t\tDisplayName:      serviceDisplayName,\n\t\tDescription:      serviceDescription,\n\t\tWorkingDirectory: pwd,\n\t\tVersion:          version.Full(),\n\t\tArguments:        args,\n\t})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"installing service: %w\", err)\n\t}\n\n\terr = mgr.Perform(ctx, &ossvc.ActionStart{\n\t\tServiceName: serviceName,\n\t})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"starting service: %w\", err)\n\t}\n\n\tif detectFirstRun(ctx, l, workDir, confPath) {\n\t\tslogutil.PrintLines(ctx, l, slog.LevelInfo, \"\", \"Almost ready!\\n\"+\n\t\t\t\"AdGuard Home is successfully installed and will automatically start on boot.\\n\"+\n\t\t\t\"There are a few more things that must be configured before you can use it.\\n\"+\n\t\t\t\"Click on the link below and follow the Installation Wizard steps to finish setup.\\n\"+\n\t\t\t\"AdGuard Home is now available at the following addresses:\")\n\t\tprintHTTPAddresses(ctx, l)\n\t}\n","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/home/service.go#L317-L353","documentation":"mgr.Install returned an error while registering AdGuard Home as an OS service. The wrapped error comes from the platform service layer (e.g. systemd unit write, sc.exe create, launchd plist install) and typically indicates privilege or filesystem problems.","triggerScenarios":"Running 'AdGuardHome -s install' without root/administrator rights; a service with the same name already existing; inability to write the unit file/plist/registry entry; unsupported init system on Linux.","commonSituations":"Plain user shell instead of sudo; leftover AdGuardHome service from a previous install; read-only /etc or /Library/LaunchDaemons; running inside a container without an init system.","solutions":["Re-run with elevated privileges (sudo / admin shell)","Remove or stop the pre-existing conflicting service first ('AdGuardHome -s uninstall' or systemctl delete the unit)","Verify the platform actually has a supported service manager (systemd, launchd, Windows SCM)","Check filesystem writability of the service definition location"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// pre-flight: can we write the service definition location?\nif info, err := os.Stat(\"/etc/systemd/system\"); err != nil || !info.IsDir() {\n    log.Fatal(\"systemd not available\")\n}","typeGuard":null,"tryCatchPattern":"// after\nerr := handleServiceInstallCmd(...)\nif err != nil && strings.Contains(err.Error(), \"installing service\") {\n    // inspect inner error, likely EPERM/EEXIST\n}","preventionTips":["Always install services with elevated privileges","Uninstall existing definitions before reinstalling","Confirm the platform has a supported service manager"],"tags":["service-management","install","privileges"],"backgroundTag":"service-install-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}