Mapping and Expression Errors v2

Use the diagnostic Code, Path, message, and Expected shape in Problems to identify the failing Property. Correct syntax and scope before changing data types or adding extra Steps.

Malformed reference

References must use one balanced pair of braces:

{.customerId}
{getCustomer.Customer.id}

Check for unmatched or nested braces, trailing dots, whitespace in an unquoted segment, and an unfinished quoted name. Quote a segment containing punctuation or spaces:

{readRecord.Record."customer-name"}

Missing Step or Property

References are case-sensitive. Confirm the exact Step, Return, and nested Property names in Canvas or YAML.

If a Node returns fields discovered only at runtime, run it with representative data and use Infer a Schema. If a Node or Sub-Workflow contract changed, refresh or recreate the Step from the current template.

Forward or out-of-scope reference

A Step can use Workflow Parameters and Returns available earlier in its current execution scope. Move the consumer after the producer or move both into a valid shared scope.

Inside a collection mapping, child Expressions must use the source collection's item scope. Inside a container Step, do not reference a child Return from a sibling branch where it is not guaranteed to exist.

Unknown function or wrong arguments

Use Expression autocomplete and hover information to select a current function and signature. Function names are resolved without regard to case, but the arguments, count, and types must match.

Common collection restrictions include:

  • FILTER requires a direct Step Return source and exactly one predicate.
  • GROUPBY requires a direct Step Return source and unique direct child keys.
  • A container with child Properties accepts a pure reference or a supported container function such as FILTER, GROUPBY, PLUCK, FIRST, LAST, or MAKEARRAY.
  • Aggregate source functions consume a collection; _OF variants consume separate scalar arguments.

Scalar, object, or collection mismatch

Read the diagnostic's Expected value, then inspect the target contract:

  • Use a leaf Property for a scalar.
  • Use Type: object with named child Properties for a structured object.
  • Use Type: array with child Properties that describe one item.
  • Put the collection source on the Array's parent Expression so child mappings run once per item.
  • Use MAKEARRAY when one value must become a one-item collection.

Do not place a complex object or Array of objects in literal Value. Use nested mappings or parse a document first.

Incompatible operator types

Operators do not provide arbitrary automatic conversion. Compare compatible values and parse or format at an explicit boundary. Use NUMBERVALUE for invariant numeric text, TEXTVALUE for text output, and DATEVALUE for dates whose input format is known.

Remember that + can mean numeric addition or compatible string concatenation. Use CONCAT when text composition is clearer.

Preview is empty or unavailable

Preview is compile-sample based. An empty result can mean that the source lacks a design-time sample (Sample: somevalue), not that the runtime mapping will be empty.

If the Preview tab says No preview available, resolve blocking diagnostics first. If it says No expressions to preview, confirm that the target uses Expression rather than Value. Use controlled Debug for results that require an external Node call.

Connection errors

Select a Connection from the Connection editor. Confirm that the Connection:

  • Has a value in the selected Environment.
  • Is assigned to a compatible Cluster.
  • Is accessible to the current user and Workflow.

Finish the diagnosis

  1. Fix YAML and schema errors first.
  2. Fix the innermost missing reference or shape error at the reported path.
  3. Recheck Problems after the idle compile completes.
  4. Inspect the result in Preview.
  5. Debug with a small representative input.
  6. Inspect the actual Step input, Return, and error in Logs.

See also

See Workflow Validation, Expression Syntax, and Mapping Functions.