Diagnostics Reference

Authoring diagnostics contain a stable code, phase, message, file, one-based line/column location, zero-based byte offset, and optional hint.

Text

WOML validation error [WOML_UNKNOWN_ELEMENT] at workflow.woml:25:7:
Unknown WOML element <on-finish>.

The stable code is for tools and support. The location and message are for the author. A translated JavaScript failure points into the original .woml when that location can be preserved.

Diagnostic shape

TypeScript

type WomlDiagnostic = {
  code: string;
  phase: 'parse' | 'validation' | 'compile' | 'runtime';
  message: string;
  file: string;
  location: {
    start: { line: number; column: number; offset: number };
    end?: { line: number; column: number; offset: number };
  };
  hint?: string;
};

WOML may return several sorted diagnostics with one primary problem. Fix structural parse and validation errors before treating every later diagnostic as independent.

Representative codes

Code	Meaning	What to inspect
`WOML_UNKNOWN_ELEMENT`	Unsupported or misplaced tag.	Spelling, parent element, installed WOML version.
`WOML_UNKNOWN_ATTRIBUTE`	Unsupported attribute at this position.	Exact attribute name and tag profile.
`WOML_DUPLICATE_ID`	Durable identity collision.	All executable and control-flow IDs in the workflow.
`WOML_INVALID_REFERENCE`	Malformed declarative reference.	Exact dot-path syntax; move computation into JavaScript.
`WOML_UNKNOWN_REFERENCE`	Referenced producer or property root is unknown.	IDs and allowed binding roots.
`WOML_REFERENCE_NOT_DOMINATING`	Output is not guaranteed before use.	Branch, fork, parallel, or route structure.
`WOML_REFERENCE_NOT_AVAILABLE`	A required runtime nested property is missing.	Actual prior step result and payload contract.
`WOML_BRANCH_TEST_NOT_BOOLEAN`	`<when>` did not resolve to boolean.	Return `true` or `false`, not truthy strings or numbers.
`WOML_SWITCH_VALUE_INVALID`	Switch input was not a string.	Normalize the value in a prior step.
`WOML_TRIGGER_SCHEMA_INVALID`	Trigger payload failed schema validation.	Caller body and inline JSON Schema.
`WOML_TRIGGER_IDEMPOTENCY_CONFLICT`	Occurrence ID was reused with changed data.	Publisher identity generation and payload stability.
`WOML_POLICY_QUEUE_FULL`	Runtime policy queue rejected admission.	Concurrency, rate limit, capacity, and producer pressure.
`WOML_WORKFLOW_TIMED_OUT`	Total workflow deadline won.	`<config timeout>`, slow effects, waits, and queueing.
`WOML_WORKFLOW_TARGET_NOT_FOUND`	Called workflow is not actively owned.	Load caller and callee in the same deployment/state authority.
`WOML_WORKFLOW_CALL_CYCLE`	Call lineage would form a cycle.	Parent/child call graph.
`WOML_WORKFLOW_CALL_WAIT_UNSUPPORTED`	Synchronous target can wait for approval.	Use `start()` or redesign the waiting boundary.

Runtime service errors

Managed capabilities throw WomlServiceError with a service, operation, call ID, retryable flag, ambiguous flag, and bounded safe details. retryable describes the failure class; it does not mean WOML can replay every external side effect safely. ambiguous means the engine cannot prove whether an effect committed.

Use JSON in automation

Terminal

woml check workflows/ --json
woml get run_abc123 --json

CI should match the stable code and phase. Human wording can improve without forcing every downstream script to change.

Exit behavior

A non-zero exit means a finite command failed. Use --json for CI and automation, and preserve the code rather than matching human prose.

Long-lived run, inspect, and log-follow commands normally end through Ctrl+C, a supervisor signal, or an explicit stop. Their lifetime is not itself a stuck command: staying alive is how automation receives future triggers.