nanocoai/nanoclaw · warning

Unknown system action

Error message

Unknown system action

What it means

Logged when a system action message in outbound.db names an action that is not in the delivery-action registry. The host's deliverMessage path dispatches system actions by name via getDeliveryAction(action); an unknown name falls through to this warn and the message is silently dropped (no delivery).

Source

Thrown at src/delivery.ts:625

  return (content, session) => runGuarded(action, entry.guard, entry.handler, content, session, null);
}

/**
 * Handle system actions from the container agent.
 * These are written to messages_out because the container can't write to inbound.db.
 * The host applies them to inbound.db here.
 */
async function handleSystemAction(content: Record<string, unknown>, session: Session): Promise<void> {
  const action = content.action as string;
  log.info('System action from agent', { sessionId: session.id, action });

  const registered = getDeliveryAction(action);
  if (registered) {
    await registered(content, session);
    return;
  }

  log.warn('Unknown system action', { action });
}

export function stopDeliveryPolls(): void {
  activePolling = false;
  sweepPolling = false;
}

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Check the exact action string in the messages_out row (query outbound.db) against the registered action names in src/delivery.ts registry
2. If the action was renamed in an upgrade, update the writer or drain the stale row
3. Verify the module that registers the action is imported (barrel self-registration) and host logs show no import failure
4. Delete/deliver the orphan row so the poll stops retracing it

Example fix

// before
await writeSystemAction(outDb, { action: 'scheduel_task', content });

// after
await writeSystemAction(outDb, { action: 'schedule_task', content });

import { getDeliveryAction } from './delivery.js';
function isKnownSystemAction(action: string): boolean {
  return getDeliveryAction(action) !== undefined;
}
// before writing: assert isKnownSystemAction(action)

When it happens

Trigger: An agent or host code writes a messages_out row with type 'system' whose action string is misspelled, removed in a version upgrade, or registered in a different module that failed to import/self-register.

Common situations: Upgrading NanoClaw where a system action was renamed or removed; a custom agent writes an ad-hoc system action; a module registering an action failed to load so its registry entry is missing.

Related errors

• Delivery batch-preview hook failed
• Post-delivery hook failed
• Malformed outbound row — delivering best-effort
• Delivery action denied by guard
• Message delivery failed, will retry

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