< woml />
View on GitHub

Troubleshooting

Start with the first WOML diagnostic code and source location rather than the final process message. A stable code identifies the class of problem; the message and hint explain this occurrence.

A five-minute investigation path

  1. Run woml check against the same deployment inputs and configuration.
  2. Read the first diagnostic's file, line, column, code, and hint.
  3. If startup succeeds but a run fails, copy its run ID.
  4. Use woml get <runId> and woml <runId> --logs.
  5. Open woml inspect to check queues, waits, and runtime health.
  6. Run a provider doctor or inspect startup diagnostics for communication problems.

Authoring failures

Run woml check. Confirm:

  • the document has one valid <woml> root and profile;
  • tags are allowed in their current parent;
  • workflow-wide executable IDs are unique;
  • declarative references are exact dot paths and point to guaranteed earlier output;
  • required attributes and trigger schemas are valid;
  • scripts return finite JSON-compatible values;
  • imported modules use named exports and supported local paths.

WOML_UNKNOWN_ELEMENT often means either a misspelled tag or a valid tag in the wrong location. WOML_REFERENCE_NOT_DOMINATING means a step could finish without the referenced producer running, not merely that the ID exists.

Runtime failures

Use woml get <runId>, <runId> --logs, and woml inspect. Check whether the run is queued, waiting for approval, cancelled, timed out, or failed in one definitive attempt.

When a host crashes after an external operation started but before its result was recorded, WOML may report interrupted or ambiguous work instead of replaying the effect. This is a safety behavior, not data loss. Investigate the external system using stable operation identity before deciding what business recovery should do.

Provider failures

Run the provider doctor where available:

Terminal
woml telegram doctor --destination <chatId>
woml discord doctor --destination <channelId>
woml whatsapp doctor --phone-number-id <id>

Verify credential type, scopes or intents, destination membership, callback signatures, and that only one process owns a long-poll or socket connection. For Slack, inspect startup diagnostics and confirm Socket Mode, event subscriptions, bot scopes, and channel membership.

Startup failures

Confirm state/storage permissions, port availability, all referenced secrets, valid runtime config, and that the globally installed WOML version supports the workflow syntax.

If a newly added tag is reported as unknown after the source was updated, check which binary is running:

Terminal
which woml
woml --version

A global npm installation can still point to an older release even when the local repository contains newer source. Rebuild or install the intended package version, then run woml check again.

Background runtime failures

If woml run workflows/ --background fails, read the exact runtime log path printed by the CLI. A detached child can fail after the launcher begins but before readiness; the log contains the actionable port, provider, state, or secret error.

CI-only failures

Reproduce the exact command and versions printed in CI. Pay attention to Bun, Rust, Clippy, platform package, and test shard. A timeout in a live-process test may be load-sensitive; an artifact upload ETIMEDOUT is normally infrastructure/network failure rather than a WOML compilation failure.

Use Diagnostics Reference for stable codes and Current Limitations before trying to work around a deliberately unsupported contract.