Troubleshooting

This page documents common validation errors, their root causes, and corrected examples. It also provides a normative debugging checklist.

Common Validation Errors

Missing Required Root Property

Error message:

must have required property 'workflows'
must have required property 'name'

Root cause: The root object is missing one or both required properties: name or workflows.

{
  "workflows": [
    {
      "intents": ["greeting"],
      "actions": [
        {
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

Missing: name

{
  "name": "Greeting Bot",
  "workflows": [
    {
      "intents": ["greeting"],
      "actions": [
        {
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

Missing Required Workflow Properties

Error message:

/workflows/0 must have required property 'intents'
/workflows/0 must have required property 'actions'

Root cause: Every workflow object MUST contain both intents and actions.

{
  "name": "My Bot",
  "workflows": [
    {
      "name": "greeting",
      "actions": [
        {
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

Missing: intents

{
  "name": "My Bot",
  "workflows": [
    {
      "name": "greeting",
      "intents": ["greeting"],
      "actions": [
        {
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

Empty Message Object

Error message:

/workflows/0/actions/0/send/message must match at least one schema in anyOf

Root cause: The message object does not contain any of the required content fields (text, media, carousel, list, buttons, quickReplies, richCard, or title).

{
  "send": {
    "message": {}
  }
}

Carousel With Fewer Than 2 Cards

Error message:

/workflows/0/actions/0/send/message/carousel must NOT have fewer than 2 items

Root cause: The carousel array MUST contain a minimum of 2 items. A single-card carousel is invalid.

{
  "send": {
    "message": {
      "carousel": [
        {
          "title": "Acme Pro Runner",
          "description": "Lightweight carbon-fiber sole.",
          "media": "https://cdn.acme.com/products/pro-runner.jpg"
        }
      ]
    }
  }
}

Only 1 card — minimum is 2.

{
  "send": {
    "message": {
      "carousel": [
        {
          "title": "Acme Pro Runner",
          "description": "Lightweight carbon-fiber sole.",
          "media": "https://cdn.acme.com/products/pro-runner.jpg"
        },
        {
          "title": "Acme Trail Blazer",
          "description": "All-terrain grip with waterproof membrane.",
          "media": "https://cdn.acme.com/products/trail-blazer.jpg"
        }
      ]
    }
  }
}

Carousel With More Than 10 Cards

Error message:

/workflows/0/actions/0/send/message/carousel must NOT have more than 10 items

Root cause: The carousel array MUST NOT exceed 10 items.

{
  "send": {
    "message": {
      "carousel": [
        { "title": "Product 1", "description": "Desc 1", "media": "https://cdn.acme.com/p1.jpg" },
        { "title": "Product 2", "description": "Desc 2", "media": "https://cdn.acme.com/p2.jpg" },
        { "title": "Product 3", "description": "Desc 3", "media": "https://cdn.acme.com/p3.jpg" },
        { "title": "Product 4", "description": "Desc 4", "media": "https://cdn.acme.com/p4.jpg" },
        { "title": "Product 5", "description": "Desc 5", "media": "https://cdn.acme.com/p5.jpg" },
        { "title": "Product 6", "description": "Desc 6", "media": "https://cdn.acme.com/p6.jpg" },
        { "title": "Product 7", "description": "Desc 7", "media": "https://cdn.acme.com/p7.jpg" },
        { "title": "Product 8", "description": "Desc 8", "media": "https://cdn.acme.com/p8.jpg" },
        { "title": "Product 9", "description": "Desc 9", "media": "https://cdn.acme.com/p9.jpg" },
        { "title": "Product 10", "description": "Desc 10", "media": "https://cdn.acme.com/p10.jpg" },
        { "title": "Product 11", "description": "Desc 11", "media": "https://cdn.acme.com/p11.jpg" }
      ]
    }
  }
}

11 cards — maximum is 10.

{
  "send": {
    "message": {
      "carousel": [
        { "title": "Product 1", "description": "Desc 1", "media": "https://cdn.acme.com/p1.jpg" },
        { "title": "Product 2", "description": "Desc 2", "media": "https://cdn.acme.com/p2.jpg" },
        { "title": "Product 3", "description": "Desc 3", "media": "https://cdn.acme.com/p3.jpg" },
        { "title": "Product 4", "description": "Desc 4", "media": "https://cdn.acme.com/p4.jpg" },
        { "title": "Product 5", "description": "Desc 5", "media": "https://cdn.acme.com/p5.jpg" },
        { "title": "Product 6", "description": "Desc 6", "media": "https://cdn.acme.com/p6.jpg" },
        { "title": "Product 7", "description": "Desc 7", "media": "https://cdn.acme.com/p7.jpg" },
        { "title": "Product 8", "description": "Desc 8", "media": "https://cdn.acme.com/p8.jpg" },
        { "title": "Product 9", "description": "Desc 9", "media": "https://cdn.acme.com/p9.jpg" },
        { "title": "Product 10", "description": "Desc 10", "media": "https://cdn.acme.com/p10.jpg" }
      ]
    }
  }
}

Trimmed to 10 cards.

Button Missing Required `title` or `payload`

Error message:

/workflows/0/actions/0/send/message/buttons/0 must have required property 'title'
/workflows/0/actions/0/send/message/buttons/0 must have required property 'payload'

Root cause: Buttons of type weburl, postback, and call MUST include both title and payload.

{
  "buttons": [
    {
      "type": "weburl",
      "payload": "https://shop.acme.com"
    }
  ]
}

Missing title for weburl button.

Quick Reply Missing Required `title`

Error message:

/workflows/0/actions/0/send/message/quickReplies/0 must have required property 'title'

Root cause: Quick replies of type text and postback MUST include title.

{
  "quickReplies": [
    {
      "type": "text",
      "payload": "track_order"
    }
  ]
}

Missing title for text quick reply.

`waitFor` Missing Required `data` or `content`

Error message:

/workflows/0/actions/0/waitFor must have required property 'data'
/workflows/0/actions/0/waitFor must have required property 'content'

Root cause: Both data and content are required in a waitFor object.

{
  "waitFor": {
    "timeout": "5m"
  }
}

Missing data and content.

Invalid `content` Attribute Name in `waitFor`

Error message:

/workflows/0/actions/0/waitFor/content must match pattern "^[a-zA-Z][a-zA-Z0-9_]*$"

Root cause: The content attribute name MUST start with a letter and contain only letters, digits, and underscores. Hyphens, dots, and leading digits are not permitted.

{
  "waitFor": {
    "data": "text",
    "content": "user-email"
  }
}

user-email contains a hyphen — not permitted.

Invalid `attributePath` in `assignAttributes`

Error message:

/workflows/0/actions/0/assignAttributes/attributes/0/attributePath must match pattern "^[a-zA-Z][a-zA-Z0-9_.]*$"

Root cause: attributePath MUST match ^[a-zA-Z][a-zA-Z0-9_.]*$. It may use dot notation for nested paths but MUST start with a letter.

{
  "assignAttributes": {
    "attributes": [
      {
        "attributePath": "2ndAddress",
        "value": "123 Main St"
      }
    ]
  }
}

2ndAddress starts with a digit — not permitted.

`send.request` POST Without `content`

Error message:

/workflows/0/actions/0/send/request must have required property 'content'

Root cause: When method is POST, PUT, or PATCH, the content property is required.

{
  "send": {
    "request": {
      "url": "https://api.acme.com/v1/leads",
      "method": "POST",
      "dataFormat": "json",
      "headers": {
        "Authorization": "Bearer {apiToken}"
      }
    }
  }
}

method is POST but content is absent.

{
  "send": {
    "request": {
      "url": "https://api.acme.com/v1/leads",
      "method": "POST",
      "dataFormat": "json",
      "headers": {
        "Authorization": "Bearer {apiToken}",
        "Content-Type": "application/json"
      },
      "content": {
        "phone": "{contactPhone}",
        "source": "rcs_chat"
      }
    }
  }
}

`name` Exceeds Maximum Length

Error message:

/ must NOT have more than 100 characters (name)

Root cause: The root name property has a maxLength of 100 characters.

{
  "name": "Acme Corporation Complete Omnichannel Customer Support and Order Management Conversational Bot Experience Version 2",
  "workflows": []
}

Name is 111 characters — maximum is 100.

Workflow or Action Name Uses Reserved `nm:` Prefix

Error message: Runtime error — the schema does not enforce this at the JSON Schema level, but the nativeMsg platform rejects names beginning with nm: at deploy time.

Root cause: Workflow and action names MUST NOT begin with the prefix nm:. This prefix is reserved for internal nativeMsg system identifiers.

{
  "name": "Support Bot",
  "workflows": [
    {
      "name": "nm:greeting",
      "intents": ["greeting"],
      "actions": [
        {
          "name": "nm:send-welcome",
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

{
  "name": "Support Bot",
  "workflows": [
    {
      "name": "greeting",
      "intents": ["greeting"],
      "actions": [
        {
          "name": "send-welcome",
          "send": {
            "message": { "text": "Hello!" }
          }
        }
      ]
    }
  ]
}

RichCard With No Content Fields

Error message:

/workflows/0/actions/0/send/message/carousel/0 must match at least one schema in anyOf

Root cause: Each RichCard in a carousel MUST include at least one of: title, description, or media.

{
  "carousel": [
    {
      "mediaHeight": "MEDIUM",
      "cardOrientation": "VERTICAL"
    },
    {
      "title": "Acme Trail Blazer",
      "description": "All-terrain grip.",
      "media": "https://cdn.acme.com/products/trail-blazer.jpg"
    }
  ]
}

First card has no title, description, or media.

{
  "carousel": [
    {
      "title": "Acme Pro Runner",
      "description": "Lightweight carbon-fiber sole.",
      "media": "https://cdn.acme.com/products/pro-runner.jpg",
      "mediaHeight": "MEDIUM",
      "cardOrientation": "VERTICAL"
    },
    {
      "title": "Acme Trail Blazer",
      "description": "All-terrain grip.",
      "media": "https://cdn.acme.com/products/trail-blazer.jpg",
      "mediaHeight": "MEDIUM",
      "cardOrientation": "VERTICAL"
    }
  ]
}

Debugging Checklist

Follow these steps in order when an experience fails validation or does not behave as expected at runtime.

Validate against the schema locally

Run the experience JSON through AJV (Node.js), jsonschema (Python), or ajv-cli before deploying. See Quick Start — Schema Validation for complete examples. Fix all reported errors before proceeding.

Verify all required fields are present

Confirm that name and workflows exist at the root. Confirm that intents and actions exist on every workflow object. Confirm that data and content exist on every waitFor object. Confirm that content and pattern exist on every validation object.

Check attribute name patterns

All attribute names used in waitFor.content MUST match ^[a-zA-Z][a-zA-Z0-9_]*$. All attributePath values in assignAttributes MUST match ^[a-zA-Z][a-zA-Z0-9_.]*$. Names starting with digits or containing hyphens are invalid.

Confirm carousel lengths

Carousels MUST have 2–10 items.

Verify button and quick reply required fields

weburl, postback, and call buttons MUST have both title (max 25 chars) and payload (max 1000 chars). text and postback quick replies MUST have title (max 25 chars).

Check HTTP method and `content` consistency

If send.request.method is POST, PUT, or PATCH, content MUST be present. If dataFormat is json and method is POST/PUT/PATCH, content MUST be a JSON object or a string starting with {.

Confirm workflow and action names do not use the `nm:` prefix

Any name beginning with nm: will be rejected at deploy time even if it passes JSON Schema validation.

Check cross-references

Every value in execute, goto, welcomeMessageExecute, executeOnError, executeOnTimeout, and fallback MUST match an existing workflow name or action name within the experience. Typos in these references cause silent no-ops or runtime errors.

Review channel-specific constraints

If the experience targets multiple channels, ensure that rich-content actions (carousel, list, richCard, buttons, quickReplies) are restricted with channel or channelTypes conditions, and that text fallbacks are present for non-RCS channels.

Inspect placeholder syntax

Attribute placeholders use the form {attributeName}. Curly braces MUST be plain ASCII { and }. Smart quotes or Unicode variants will not be substituted. Verify that every placeholder references an attribute that is assigned before the action that reads it.

Review `Validation` objects

The pattern field MUST be a valid ECMA-262 regular expression. Unterminated or malformed patterns cause runtime errors. Test patterns against representative values before deploying.

Check for duplicate workflow names

If two workflows share the same name, resolution behavior is undefined. Ensure all workflow names within a single experience are unique.

PreviousCoding Language Examples

Last updated 2 minutes ago

Was this helpful?

Good afternoon

hashtagCommon Validation Errors

hashtagMissing Required Root Property

hashtagMissing Required Workflow Properties

hashtagEmpty Message Object

hashtagCarousel With Fewer Than 2 Cards

hashtagCarousel With More Than 10 Cards

hashtagButton Missing Required title or payload

hashtagQuick Reply Missing Required title

hashtagwaitFor Missing Required data or content

hashtagInvalid content Attribute Name in waitFor

hashtagInvalid attributePath in assignAttributes

hashtagsend.request POST Without content

hashtagname Exceeds Maximum Length

hashtagWorkflow or Action Name Uses Reserved nm: Prefix

hashtagRichCard With No Content Fields

hashtagDebugging Checklist

hashtagValidate against the schema locally

hashtagVerify all required fields are present

hashtagCheck attribute name patterns

hashtagConfirm carousel lengths

hashtagVerify button and quick reply required fields

hashtagCheck HTTP method and content consistency

hashtagConfirm workflow and action names do not use the nm: prefix

hashtagCheck cross-references

hashtagReview channel-specific constraints

hashtagInspect placeholder syntax

hashtagReview Validation objects

hashtagCheck for duplicate workflow names

Common Validation Errors

Missing Required Root Property

Missing Required Workflow Properties

Empty Message Object

Carousel With Fewer Than 2 Cards

Carousel With More Than 10 Cards

Button Missing Required `title` or `payload`

Quick Reply Missing Required `title`

`waitFor` Missing Required `data` or `content`

Invalid `content` Attribute Name in `waitFor`

Invalid `attributePath` in `assignAttributes`

`send.request` POST Without `content`

`name` Exceeds Maximum Length

Workflow or Action Name Uses Reserved `nm:` Prefix

RichCard With No Content Fields

Debugging Checklist

Validate against the schema locally

Verify all required fields are present

Check attribute name patterns

Confirm carousel lengths

Verify button and quick reply required fields

Check HTTP method and `content` consistency

Confirm workflow and action names do not use the `nm:` prefix

Check cross-references

Review channel-specific constraints

Inspect placeholder syntax

Review `Validation` objects

Check for duplicate workflow names