agalwood/Motrix · warning · NotifyCapabilityError

plugin.capability.unavailable

plugin.capability.unavailable

Error message

notify capability is not available in this runtime

What it means

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.

Source

Thrown at src/core/plugin/capabilities/notify.ts:51

  body: string
  icon?: 'info' | 'success' | 'error'
  urgency?: 'low' | 'normal' | 'critical'
}

export interface NotifyCapabilityHost {
  readonly available: boolean
  show(pluginId: string, opts: NotifyShowOpts): Promise<void>
}

// ---------------------------------------------------------------------------
// UnavailableNotifyHost
// ---------------------------------------------------------------------------

export class UnavailableNotifyHost implements NotifyCapabilityHost {
  readonly available = false

  async show(_pluginId: string, _opts: NotifyShowOpts): Promise<void> {
    throw new NotifyCapabilityError(
      'plugin.capability.unavailable',
      'notify capability is not available in this runtime'
    )
  }
}

View on GitHub (pinned to 1a708ee577)

Solutions

1. Check notify.available before calling show() and degrade gracefully (log, queue, skip).
2. Install a concrete NotifyCapabilityHost in the runtime configuration when notifications are required.
3. Gate the plugin's UI surfaces on notify.available.

Example fix

// before
await notify.show(pluginId, { title: 'Done' })

// after
if (notify.available) await notify.show(pluginId, { title: 'Done' })
else logger.info('task complete')

if (!notify.available) {
  logger.info('notify unavailable; skipping')
  return
}
await notify.show(pluginId, opts)

function notifyCapable(host: NotifyCapabilityHost): host is NotifyCapabilityHost & { available: true } {
  return host.available === true
}

When it happens

Trigger: 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.

Common situations: Plugin developed against a desktop runtime, deployed server-side; CI runs plugins that attempt to notify users; feature flag disabled notifications in this build.

Related errors

• plugin.lifecycle.secrets_seed_missing
• plugin.capability.bad_args
• plugin.capability.unavailable
• plugin.fs.task.not_available_outside_hook
• plugin.metadata.not_available_outside_hook

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/9736ecfe595d1f02. Report an issue: GitHub.