What causes "Post-delivery hook failed" in nanocoai/nanoclaw?

Check the error detail to identify the hook

Post-delivery hook failed

Error message

Post-delivery hook failed

What it means

A post-delivery hook (registered to run after a message is delivered) threw. The message itself was already delivered; only follow-up side effects were skipped.

Source

Thrown at src/delivery.ts:245

      if (msg.kind !== 'system' && msg.channelType !== 'agent') {
        pauseTypingRefreshAfterDelivery(session.id);
        if (msg.kind !== 'task_log') {
          await fanOutboundMessage(
            {
              id: msg.id,
              kind: msg.kind,
              platform_id: msg.platformId,
              channel_type: msg.channelType,
              content: msg.content,
            },
            session,
            agentGroup,
          );
          for (const hook of postDeliveryHooks) {
            try {
              await hook(msg, session, { firstDelivery });
            } catch (err) {
              log.warn('Post-delivery hook failed', { messageId: msg.id, sessionId: session.id, err });
            }
          }
        }
      }
    } catch (err) {
      const attempts = (deliveryAttempts.get(msg.id) ?? 0) + 1;
      deliveryAttempts.set(msg.id, attempts);
      if (attempts >= MAX_DELIVERY_ATTEMPTS) {
        log.error('Message delivery failed permanently, giving up', {
          messageId: msg.id,
          sessionId: session.id,
          attempts,
          err,
        });
        try {
          await withExistingMailboxSession(agentGroup.id, session.id, (mailbox) => mailbox.markDeliveryFailed(msg.id));
          deliveryAttempts.delete(msg.id);
        } catch (markErr) {

View on GitHub (pinned to 294ef2aee8)

Solutions

Check the error detail to identify the hook
Fix the hook's root cause (endpoint, auth, shape)
Watch for downstream effects of the missed side effect (e.g. recurrence not scheduled) and retrigger manually

Defensive patterns

Strategy: try-catch

Try / catch

try { await hook(msg, session, {firstDelivery}); } catch { /* delivery already done; log and move on */ }

Prevention

Make post-delivery hooks idempotent and fault-tolerant
Never put business-critical state exclusively in a post-delivery hook

When it happens

Trigger: Any postDeliveryHooks entry throwing on (msg, session, {firstDelivery}) — e.g. marking state in an external system, scheduling recurrence, or notification integrations that error.

Common situations: Third-party add-ons with flaky network calls; hooks written against an older message shape.

Related errors

AI-assisted analysis of nanocoai/nanoclaw@294ef2aee8 (2026-08-28). Data as JSON: /api/errors/e3f194b1f764faeb. Report an issue: GitHub.