What causes "Failed to handle spark:notify event:" in moeru-ai/airi?

Inspect the logged error to find the throwing frame inside handleIncomingSparkNotify.

Failed to handle spark:notify event:

Error message

Failed to handle spark:notify event:

What it means

The orchestrator's initialize() subscribes to 'spark:notify' events from the mods server channel; when the async handler handleIncomingSparkNotify rejects, the error is caught per-event and logged. The event is not retried at this layer (retry scheduling lives inside the queue processing), and the subscription stays alive, so one bad event does not kill the listener.

Source

Thrown at packages/stage-ui/src/stores/character/orchestrator/store.ts:277

  async function handleSparkEmit(_: WebSocketBaseEvent<'spark:emit', WebSocketEvents['spark:emit']>) {
    // Currently no-op
    return undefined
  }

  function initialize() {
    if (initialized)
      return

    initialized = true

    eventUnsubscribes.push(
      modsServerChannelStore.onEvent('spark:notify', async (event) => {
        try {
          await handleIncomingSparkNotify(event)
        }
        catch (error) {
          console.warn('Failed to handle spark:notify event:', error)
        }
      }),
    )

    eventUnsubscribes.push(
      modsServerChannelStore.onEvent('spark:emit', async (event) => {
        try {
          await handleSparkEmit(event)
        }
        catch (error) {
          console.warn('Failed to handle spark:emit event:', error)
        }
      }),
    )

    startTicker()
  }

View on GitHub (pinned to 677329427f)

Solutions

Inspect the logged error to find the throwing frame inside handleIncomingSparkNotify.
Validate/normalize incoming spark event payloads at the channel boundary before dispatch.
Update mods and orchestrator to the same event schema version.
If it fires once at startup before stores are ready, defer initialize() until dependent stores are initialized.

Defensive patterns

Strategy: try-catch

Validate before calling

function isSparkNotifyPayload(event: unknown): event is { /* expected shape */ } {
  // validate with a schema (Valibot) at the channel boundary
  return sparkNotifySchema.safeParse(event).success
}

Try / catch

modsServerChannelStore.onEvent('spark:notify', async (event) => {
  try {
    await handleIncomingSparkNotify(event)
  }
  catch (error) {
    console.warn('Failed to handle spark:notify event:', error)
    // subscription stays alive; isolate the failure to this event
  }
})

Prevention

Schema-validate incoming events before dispatch so bad payloads are rejected loudly with context.
Keep handler side-effects idempotent so a retried event cannot double-apply.
Initialize dependent stores before subscribing in initialize().

When it happens

Trigger: A spark:notify event arrives whose processing throws — invalid event payload, scheduling logic rejecting the event, or the same processSparkNotify path failing before/while entering the retry queue.

Common situations: Mod emitting an event with unexpected/missing fields; version skew between mod SDK and orchestrator schema; a bug in computeNextRunAt/scheduling for edge-case payloads; downstream store state not initialized when the event lands.

Related errors

AI-assisted analysis of moeru-ai/airi@677329427f (2026-08-18). Data as JSON: /api/errors/79e19a2f46b63ead. Report an issue: GitHub.