Workflow Validation Errors
This page documents all validation error codes that can occur when creating or updating a workflow. Each error includes a description, common causes, and how to fix it.
Error Code Reference
Structure Errors (STRUCT)
STRUCT-001: Workflow Required
Message: The 'workflow' section is required at the root of your YAML document.
Cause: The workflow YAML document is missing the required workflow section.
Solution: Add a workflow section at the root level with at minimum name and workflowId properties:
workflow:
name: "My Workflow"
workflowId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
STRUCT-002: Workflow Name Required
Message: The workflow 'name' property is required.
Cause: The workflow section is missing the name property.
Solution: Add a descriptive name to your workflow:
workflow:
name: "Send Order Confirmation Email"
workflowId: "..."
STRUCT-003: WorkflowId Required
Message: The 'workflowId' property is required and must be a valid GUID.
Cause: The workflow section is missing the workflowId property.
Solution: Generate a unique GUID and add it to your workflow:
workflow:
name: "My Workflow"
workflowId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Use an online GUID generator or your IDE's built-in tools to create a unique identifier.
STRUCT-004: Priority Out of Range
Message: The workflow priority value is out of range. Priority must be between 0 and 100.
Cause: The priority property contains a value outside the valid range (0-100).
Solution: Set priority to a value between 0 (lowest) and 100 (highest):
workflow:
name: "My Workflow"
workflowId: "..."
priority: 50 # Default priority
STRUCT-005: Activity Name Required
Message: Activity name is required.
Cause: An activity in the activities array is missing the name property.
Solution: Add a unique name to each activity:
activities:
- name: "Send Notification"
steps:
- task: SendEmail@1
STRUCT-006: Duplicate Activity Name
Message: Duplicate activity name found.
Cause: Two or more activities have the same name.
Solution: Ensure each activity has a unique name. Activity names are used to reference outputs:
activities:
- name: "Validate Order" # Unique
steps: [...]
- name: "Send Email" # Unique
steps: [...]
STRUCT-007: Activity Steps Required
Message: Activity must have at least one step in the 'steps' array.
Cause: An activity has no steps defined or the steps property is missing.
Solution: Add at least one step to each activity:
activities:
- name: "My Activity"
steps:
- task: MyTask@1
inputs:
param1: "value"
Trigger Errors (TRIGGER)
TRIGGER-001: Invalid Trigger Type
Message: Invalid trigger type. Valid types: Entity, Manual.
Cause: The type property contains an unsupported value.
Solution: Use either Entity or Manual as the trigger type:
triggers:
- type: Entity # Triggered by database changes
entityName: Order
eventType: Modified
position: After
- type: Manual # Triggered by user action or API
TRIGGER-002: EntityName Required
Message: The 'entityName' property is required for Entity triggers.
Cause: An Entity trigger is missing the required entityName property.
Solution: Specify which entity should trigger the workflow:
triggers:
- type: Entity
entityName: Order # Required for Entity type
eventType: Modified
position: After
TRIGGER-003: Invalid Event Type
Message: Invalid event type. Valid types: Added, Modified, Deleted.
Cause: The eventType property contains an unsupported value.
Solution: Use one of the valid event types:
triggers:
- type: Entity
entityName: Order
eventType: Added # When entity is created
# eventType: Modified # When entity is updated
# eventType: Deleted # When entity is removed
TRIGGER-004: Invalid Position
Message: Invalid trigger position. Valid positions: Before, After.
Cause: The position property contains an unsupported value.
Solution: Use either Before or After:
triggers:
- type: Entity
entityName: Order
eventType: Modified
position: After # Executes after database save
# position: Before # Executes before save (Sync mode only)
Before triggers must use executionMode: Sync. Async workflows cannot have Before triggers.
Task Errors (TASK)
TASK-001: Task Name Required
Message: The 'task' property is required for each step.
Cause: A step in the workflow is missing the task property.
Solution: Specify a task handler or control flow task:
steps:
- task: SendEmail@1 # Task handler
inputs:
to: "{{customer.email}}"
- task: foreach # Control flow task
collection: items
steps: [...]
TASK-002: Invalid Task Name Format
Message: Invalid task name format. Expected format: TaskName or TaskName@Version.
Cause: The task name doesn't follow the required naming pattern.
Valid Formats:
TaskName- Uses latest versionTaskName@1- Uses specific versionNamespace/TaskName@1- Namespaced task with version
Examples:
steps:
- task: SendEmail@1 # Valid
- task: Order/Create@1 # Valid
- task: NovaPoshta/Tracking@2 # Valid
- task: foreach # Valid (control flow)
- task: Task@ # Invalid - missing version number
- task: Task@abc # Invalid - version must be integer
TASK-003: Task Handler Not Found (Warning)
Message: Task handler not found in the system.
Cause: The specified task handler is not registered in the system.
Solution:
- Verify the task name spelling
- Check the task version exists
- Ensure the required module is installed
- See the Workflow Tasks documentation for available tasks
Control Flow Errors (CTRL)
CTRL-001: Foreach Collection Required
Message: The 'collection' property is required for 'foreach' tasks.
Cause: A foreach task is missing the collection property.
Solution: Specify the collection to iterate over:
- task: foreach
collection: order.commodities # Required
item: commodity # Optional (default: "item")
steps:
- task: ProcessCommodity@1
inputs:
data: "{{commodity}}"
CTRL-002: Foreach Steps Required
Message: The 'steps' array is required for 'foreach' tasks.
Cause: A foreach task has no steps defined.
Solution: Add steps to execute for each item:
- task: foreach
collection: items
steps: # Required
- task: ProcessItem@1
inputs:
item: "{{item}}"
CTRL-003: Switch Cases Required
Message: The 'cases' array is required for 'switch' tasks.
Cause: A switch task has no cases defined.
Solution: Define at least one case with conditions:
- task: switch
cases: # Required
- when:
- expression: "[status] == 'shipped'"
steps:
- task: SendShippedEmail@1
default: # Optional
- task: SendDefaultEmail@1
CTRL-004: Switch Case When Required
Message: The 'when' condition array is required for switch case.
Cause: A switch case is missing the when conditions.
Solution: Add conditions that determine when the case executes:
cases:
- when: # Required
- expression: "[order.status] == 'shipped'"
steps:
- task: NotifyCustomer@1
CTRL-005: Switch Case Steps Required
Message: The 'steps' array is required for switch case.
Cause: A switch case has no steps to execute.
Solution: Define steps for each case:
cases:
- when:
- expression: "[status] == 'active'"
steps: # Required
- task: ProcessActive@1
CTRL-006: While Conditions Required
Message: The 'conditions' array is required for 'while' tasks.
Cause: A while task has no conditions defined.
Solution: Define conditions that control loop continuation:
- task: while
conditions: # Required
- expression: "[counter] < 10"
steps:
- task: IncrementCounter@1
Always ensure your conditions will eventually become false, or use maxIterations to prevent infinite loops (default: 10,000).
CTRL-007: While Steps Required
Message: The 'steps' array is required for 'while' tasks.
Cause: A while task has no steps defined.
Solution: Add steps to execute on each iteration:
- task: while
conditions:
- expression: "[hasMore]"
steps: # Required
- task: FetchNextPage@1
- task: ProcessPage@1
Expression Errors (EXPR)
EXPR-001: Invalid Expression Syntax
Message: Invalid NCalc expression syntax.
Cause: The expression in a condition has syntax errors.
Common Issues:
- Unbalanced parentheses or brackets
- Unclosed string literals
- Missing operands
- Invalid operators
Valid Expression Examples:
conditions:
- expression: "[order.status] == 'shipped'"
- expression: "[amount] > 100 AND [status] = 'active'"
- expression: "isNullOrEmpty([customer.email]) = false"
- expression: "count([items]) > 0"
- expression: "any([tags], [each] = 'priority')"
Invalid Expressions:
# Missing closing parenthesis
- expression: "count([items]"
# Incomplete comparison
- expression: "[status] == "
# Unbalanced brackets
- expression: "[order.status == 'shipped'"
See Workflow Expressions for complete syntax documentation.
EXPR-002: Invalid Template Syntax
Message: Invalid template variable syntax.
Cause: A template expression {{variable}} has syntax errors.
Common Issues:
- Unbalanced braces
- Empty template
{{}} - Triple braces
{{{}}}
Valid Templates:
inputs:
to: "{{customer.email}}"
subject: "Order {{order.id}} shipped"
body: "Hello {{contact.firstName}}"
Invalid Templates:
# Unclosed braces
to: "{{customer.email"
# Empty variable
subject: "Order {{}}"
# Triple braces (not allowed)
body: "{{{data}}}"
Output Errors (OUTPUT)
OUTPUT-001: Output Name Required
Message: Output name is required.
Cause: An output in the outputs array is missing the name property.
Solution: Add a name to identify each output:
outputs:
- name: result # Required
mapping: "{{Activity.Task.response}}"
- name: document
mapping: "{{GenerateDoc.file}}"
Input Errors (INPUT)
INPUT-001: Input Name Required
Message: Input name is required.
Cause: An input in the inputs array is missing the name property.
Solution: Add a name to identify each input parameter:
inputs:
- name: orderId # Required
type: integer
required: true
- name: sendEmail
type: boolean
default: true
Schedule Errors (SCHED)
SCHED-001: Invalid Cron Expression
Message: Invalid cron expression.
Cause: The cron expression doesn't follow the standard format.
Cron Format: minute hour day-of-month month day-of-week
Valid Examples:
schedules:
- cron: "0 0 * * *" # Midnight daily
- cron: "*/15 * * * *" # Every 15 minutes
- cron: "0 9 * * 1-5" # 9 AM weekdays
- cron: "0 0 1 * *" # First day of month
Field Ranges:
| Field | Values |
|---|---|
| Minute | 0-59 |
| Hour | 0-23 |
| Day of month | 1-31 |
| Month | 1-12 |
| Day of week | 0-6 (Sunday=0) |
Use crontab.guru to build and validate cron expressions.
YAML Errors (YAML)
YAML-001: YAML Empty
Message: The workflow YAML document is empty.
Cause: No content was provided in the workflow definition.
Solution: Provide a valid YAML workflow definition.
YAML-002: YAML Parse Error
Message: Failed to parse YAML document.
Cause: The YAML has syntax errors such as:
- Incorrect indentation
- Missing colons
- Invalid characters
- Unquoted special characters
Solution: Validate your YAML syntax. Common fixes:
- Use consistent indentation (2 spaces recommended)
- Quote strings containing special characters
- Ensure colons have proper spacing
# Correct
workflow:
name: "My Workflow: Special Edition" # Quoted due to colon
# Incorrect
workflow:
name: My Workflow: Special Edition # Unquoted colon causes error
Flow Workflow Errors (FLOW)
Flow workflows have additional validation rules specific to state machine configurations.
FLOW-001: Entity Required
Message: The 'entity' section is required for Flow workflows.
Cause: A Flow workflow is missing the entity configuration.
Solution: Add the entity section specifying what entity the flow manages:
workflow:
workflowType: Flow
# ...
entity:
name: "Order"
type: "ParcelShipment"
FLOW-002: Entity Name Required
Message: The 'entity.name' property is required.
Cause: The entity section is missing the name property.
Solution: Specify the entity name:
entity:
name: "Order" # Required
type: "ParcelShipment"
FLOW-003: Invalid Entity Name
Message: Invalid entity name. Valid entity names are: Order, Commodity, AccountingTransaction, Contact, Workflow, OrganizationConfig, AppModule, Attachment, OrderCommodity, TrackingEvent, JobOrder.
Cause: The entity name is not a supported entity type for Flow workflows.
Solution: Use one of the valid entity names listed in the error message.
FLOW-004: Entity Type Required
Message: The 'entity.type' property is required for certain entities.
Cause: The entity requires a type but none was specified. Required for: Order, AccountingTransaction, Contact.
Solution: Add the appropriate type:
entity:
name: "Order"
type: "ParcelShipment" # Required for Order
# Or for AccountingTransaction:
entity:
name: "AccountingTransaction"
type: "Invoice" # Required: Invoice, Bill, or CreditMemo
# Or for Contact:
entity:
name: "Contact"
type: "Customer" # Required: Customer, Carrier, Vendor, etc.
FLOW-005: Invalid Entity Type
Message: Invalid entity type for the specified entity.
Cause: The entity type value is not valid for the specified entity.
Valid Order Types:
- Order, Quote, WarehouseReceipt, Purchase, ParcelShipment
- AirShipmentOrder, OceanShipmentOrder, CargoMovement, EntityType
- PickupOrder, LoadOrder, BookingOrder, Freight, DeliveryOrder
Valid AccountingTransaction Types:
- Invoice, Bill, CreditMemo
Valid Contact Types:
- Customer, Carrier, Vendor, Contact, Driver, Employee
- SalesPerson, ForwardingAgent, FactoringCompany, Lead
- PoolPoint, DistributionCenter, Store, ContactUser, USPPI
Solution: Use a valid type for your entity:
entity:
name: "Order"
type: "ParcelShipment" # Valid Order type
FLOW-010: Multiple Initial States
Message: Found multiple initial states. A Flow workflow can have at most one initial state.
Cause: More than one state has isInitial: true.
Solution: Ensure only one state is marked as initial:
states:
- name: "Draft"
isInitial: true # Only one state should have this
- name: "Active"
# isInitial: false # Other states should not be initial
FLOW-011: State Parent Not Found
Message: Parent state not found in states list.
Cause: A state references a parent that doesn't exist.
Solution: Ensure the parent state is defined:
states:
- name: "Active" # Parent must exist
- name: "Pending"
parent: "Active" # References existing parent
FLOW-012: Parent State Cannot Be Initial
Message: A parent state cannot be marked as initial.
Cause: A state that is used as a parent for other states also has isInitial: true.
Solution: Only leaf states (states without children) can be initial:
states:
- name: "Active"
# isInitial: true # Cannot be initial - it's a parent
- name: "Pending"
parent: "Active"
isInitial: true # Leaf state can be initial
FLOW-013: Parent State Cannot Be Final
Message: A parent state cannot be marked as final.
Cause: A state that is used as a parent for other states also has isFinal: true.
Solution: Only leaf states can be final.
FLOW-014: State Name Required
Message: State name is required.
Cause: A state is missing the name property.
Solution: Add a name to each state:
states:
- name: "Draft" # Required
isInitial: true
FLOW-015: Duplicate State Name
Message: Duplicate state name found.
Cause: Two or more states have the same name.
Solution: Ensure each state has a unique name.
FLOW-020: Transition From State Not Found
Message: Source state not found in states list.
Cause: A transition's from references a state that doesn't exist.
Solution: Ensure the source state exists:
states:
- name: "Draft"
- name: "Active"
transitions:
- name: "activate"
from: "Draft" # Must exist in states
to: "Active"
FLOW-021: Transition To State Not Found
Message: Target state not found in states list.
Cause: A transition's to references a state that doesn't exist.
Solution: Ensure the target state exists in the states list.
FLOW-022: Transition To State Must Be Leaf
Message: Transitions must target leaf states (states without children).
Cause: A transition targets a parent state instead of a leaf state.
Solution: Target a specific leaf state:
states:
- name: "Active" # Parent state
- name: "Pending"
parent: "Active" # Leaf state
transitions:
- name: "start"
from: "Draft"
to: "Pending" # Target leaf, not "Active"
FLOW-023: Invalid Transition Trigger
Message: Invalid trigger type. Valid triggers: auto, manual, event.
Cause: The transition trigger is not a valid value.
Solution: Use a valid trigger type:
transitions:
- name: "auto_transition"
trigger: "auto" # Automatic when conditions met
- name: "user_action"
trigger: "manual" # User-initiated
- name: "on_event"
trigger: "event" # External event (requires eventName)
eventName: "order.shipped"
FLOW-024: Event Name Required
Message: The 'eventName' property is required when trigger is 'event'.
Cause: A transition with trigger: event is missing the eventName property.
Solution: Add the event name:
transitions:
- name: "on_shipment"
trigger: "event"
eventName: "order.shipped" # Required for event triggers
FLOW-025: Transition Name Required
Message: Transition name is required.
Cause: A transition is missing the name property.
Solution: Add a unique name to each transition.
FLOW-026: Duplicate Transition Name
Message: Duplicate transition name found.
Cause: Two or more transitions have the same name.
Solution: Ensure each transition has a unique name.
FLOW-030: Aggregation Name Required
Message: Aggregation name is required.
Cause: An aggregation is missing the name property.
Solution: Add a name to each aggregation:
aggregations:
- name: "allDelivered" # Required
expression: "all([Order.Commodities], [each.Status] = 'Delivered')"
FLOW-031: Aggregation Expression Required
Message: Aggregation expression is required.
Cause: An aggregation is missing the expression property.
Solution: Add an expression using a valid aggregation function.
FLOW-032: Invalid Aggregation Function
Message: Invalid aggregation function. Valid functions: all, any, sum, count, first, last, distinct, groupBy.
Cause: The aggregation expression uses an unsupported function.
Solution: Use one of the supported functions:
aggregations:
- name: "allDelivered"
expression: "all([Items], [each.Status] = 'Done')"
- name: "hasActive"
expression: "any([Items], [each.Active] = true)"
- name: "totalAmount"
expression: "sum([Charges], [each.Amount])"
- name: "itemCount"
expression: "count([Items])"
FLOW-033: Duplicate Aggregation Name
Message: Duplicate aggregation name found.
Cause: Two or more aggregations have the same name.
Solution: Ensure each aggregation has a unique name.