{"record":{"id":"d1889297f7125548","repo":"AdguardTeam/AdGuardHome","slug":"starting-watcher-w","errorCode":null,"errorMessage":"starting watcher: %w","messagePattern":"starting watcher: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/aghtls/defaultmanager.go","lineNumber":257,"sourceCode":"// Refresh implements the [service.Refresher] interface for *DefaultManager.\nfunc (mgr *DefaultManager) Refresh(ctx context.Context) (err error) {\n\tmgr.logger.DebugContext(ctx, \"refreshing\")\n\n\tselect {\n\tcase mgr.updates <- UpdateSignal{}:\n\t\treturn nil\n\tcase <-ctx.Done():\n\t\treturn fmt.Errorf(\"refreshing: %w\", ctx.Err())\n\tdefault:\n\t\treturn nil\n\t}\n}\n\n// Start implements the [service.Interface] interface for *DefaultManager.\nfunc (mgr *DefaultManager) Start(ctx context.Context) (err error) {\n\terr = mgr.watcher.Start(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"starting watcher: %w\", err)\n\t}\n\n\tgo mgr.handleEvents(ctx)\n\tgo mgr.handleCertFileChange(ctx)\n\n\treturn nil\n}\n\n// Shutdown implements the [service.Interface] interface for *DefaultManager.\nfunc (mgr *DefaultManager) Shutdown(ctx context.Context) (err error) {\n\tdefer close(mgr.updates)\n\n\terr = mgr.watcher.Shutdown(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"shutting down watcher: %w\", err)\n\t}\n\n\treturn nil","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/aghtls/defaultmanager.go#L239-L275","documentation":"Failed to start the underlying fsnotify watcher that monitors TLS certificate files for changes. The wrapped error comes from watcher.Start, usually an OS-level failure to initialize inotify/ReadDirectoryChangesW.","triggerScenarios":"Calling DefaultManager.Start(ctx) when the fsnotify backend cannot create an inotify instance (fd exhaustion, inotify instances limit fs.inotify.max_user_instances) or after the watcher was already started/shut down.","commonSituations":"Running in a resource-constrained container with a low max_user_instances limit; file-descriptor exhaustion from leaking watchers; calling Start twice on the same manager.","solutions":["Raise fs.inotify.max_user_instances if the OS reports too many inotify instances","Check for fd leaks (lsof) if ENOMEM/EMFILE appears in the wrapped error","Ensure Start is called exactly once per manager lifecycle"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if rlimitCheck() { /* ensure fds available */ }","typeGuard":null,"tryCatchPattern":"if err := mgr.Start(ctx); err != nil {\n    log.Fatal(\"tls manager failed to start\", \"err\", err) // service cannot hot-reload certs\n}","preventionTips":["Call Start exactly once per manager","Raise fs.inotify.max_user_instances in container hosts","Avoid leaking file descriptors before Start"],"tags":["tls","fsnotify","startup","inotify"],"backgroundTag":"watcher-start-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}