{"record":{"id":"9736ecfe595d1f02","repo":"agalwood/Motrix","slug":"plugin-capability-unavailable","errorCode":"plugin.capability.unavailable","errorMessage":"notify capability is not available in this runtime","messagePattern":"notify capability is not available in this runtime","errorType":"exception","errorClass":"NotifyCapabilityError","httpStatus":null,"severity":"warning","filePath":"src/core/plugin/capabilities/notify.ts","lineNumber":51,"sourceCode":"  body: string\n  icon?: 'info' | 'success' | 'error'\n  urgency?: 'low' | 'normal' | 'critical'\n}\n\nexport interface NotifyCapabilityHost {\n  readonly available: boolean\n  show(pluginId: string, opts: NotifyShowOpts): Promise<void>\n}\n\n// ---------------------------------------------------------------------------\n// UnavailableNotifyHost\n// ---------------------------------------------------------------------------\n\nexport class UnavailableNotifyHost implements NotifyCapabilityHost {\n  readonly available = false\n\n  async show(_pluginId: string, _opts: NotifyShowOpts): Promise<void> {\n    throw new NotifyCapabilityError(\n      'plugin.capability.unavailable',\n      'notify capability is not available in this runtime'\n    )\n  }\n}\n","sourceCodeStart":33,"sourceCodeEnd":57,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/plugin/capabilities/notify.ts#L33-L57","documentation":"The runtime installed UnavailableNotifyHost, a stub whose available flag is false and whose show() always throws. This represents an environment that does not surface user-facing notifications (e.g. headless server, CI worker). The capability is wired into the plugin but backed by a no-op, so plugins must check available before relying on it.","triggerScenarios":"Plugin calls notify.show() in a headless/CLI runtime where no desktop notifications exist; running the same plugin in server mode that works in desktop mode; tests that forgot to install a notify stub.","commonSituations":"Plugin developed against a desktop runtime, deployed server-side; CI runs plugins that attempt to notify users; feature flag disabled notifications in this build.","solutions":["Check notify.available before calling show() and degrade gracefully (log, queue, skip).","Install a concrete NotifyCapabilityHost in the runtime configuration when notifications are required.","Gate the plugin's UI surfaces on notify.available."],"exampleFix":"// before\nawait notify.show(pluginId, { title: 'Done' })\n\n// after\nif (notify.available) await notify.show(pluginId, { title: 'Done' })\nelse logger.info('task complete')","handlingStrategy":"validation","validationCode":"if (!notify.available) {\n  logger.info('notify unavailable; skipping')\n  return\n}\nawait notify.show(pluginId, opts)","typeGuard":"function notifyCapable(host: NotifyCapabilityHost): host is NotifyCapabilityHost & { available: true } {\n  return host.available === true\n}","tryCatchPattern":null,"preventionTips":["Always gate notify.show() on host.available.","Treat notify as a best-effort channel; never make correctness depend on it.","When authoring a runtime, install a real NotifyCapabilityHost if notifications are expected."],"tags":["notify","capability","runtime","headless"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}