Troubleshooting

Start with the recorded events and the host logs. A UI that has stopped updating does not necessarily mean execution stopped.

Unknown definition or kind#

Register the definition on its owning module. Register child definitions as well as roots. Install the module implementing the kind. Check exact names and retain old definitions for parked runs after deployments.

A gate never resumes#

Read pendingApprovals, use the pending approvalId, and send a decision through your authorized gateway. Check correlation fields and event type. A gate has no automatic timeout. An approval.timed_out event alone does not resolve a wait for approval.decided.

Reject still executes the next node#

A completed gate means a decision arrived. Check outcome === 'approve' before requesting the action. The quickstart publishes only after an explicit approval. Its restart test also checks rejection.

The agent produces a stub response#

Supply agent({ llm }) or a runTurn implementation. Omitting the adapter intentionally uses deterministic behavior. Check server-side environment variables and the provider model ID.

SQLite fails under Node#

The @swirls/looms/core/bun-sqlite entry uses Bun's native SQLite module. Run this example with Bun, use the Cloudflare storage adapter in Workers, or implement another compatible store for a custom host.

SSE does not update#

Confirm the request reaches /runs/:id/events with the correct permission context. Preserve text/event-stream and streaming bodies through the gateway, disable buffering, and check network errors. A disconnected client should resume with Last-Event-ID; ensure retention has not removed the requested history.

Invalid input or events#

Compare the payload with the module's runtime schema. Use typed builders rather than handwritten envelopes. Compile-time payload markers do not add runtime validation. Inspect HTTP status and body; different hosts may map routing failures differently.

Global run listing returns 501#

This is the actor host contract. Use your application registry or a cross-run index; see the operations guide.

Timers do not fire after a local restart#

Reopen the affected run cell to rescan timers. A stopped Bun process cannot fire in-process timers, and the local actor host does not enumerate persisted files for you. Use Durable Objects for host-managed alarms.

Report a reproducible problem#

Include package versions, host/runtime version, a minimal definition, expected behavior, and sanitized event types/sequence. Remove credentials, prompts containing private data, and personal identifiers before opening a GitHub issue.