Ctrlk
Book a DemoVisit WebsiteOn-Demand Content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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

Missing: intents

Empty Message Object

Error message:

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

Carousel With Fewer Than 2 Cards

Error message:

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

Only 1 card — minimum is 2.

Carousel With More Than 10 Cards

Error message:

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

11 cards — maximum is 10.

Trimmed to 10 cards.

Button Missing Required title or payload

Error message:

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

Missing title for weburl button.

Quick Reply Missing Required title

Error message:

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

Missing title for text quick reply.

waitFor Missing Required data or content

Error message:

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

Missing data and content.

Invalid content Attribute Name in waitFor

Error message:

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.

user-email contains a hyphen — not permitted.

Invalid attributePath in assignAttributes

Error message:

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.

2ndAddress starts with a digit — not permitted.

send.request POST Without content

Error message:

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

method is POST but content is absent.

name Exceeds Maximum Length

Error message:

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

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.

RichCard With No Content Fields

Error message:

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

First card has no title, description, or media.

Debugging Checklist

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

1

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.

2

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.

3

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.

4

Confirm carousel lengths

Carousels MUST have 2–10 items.

5

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).

6

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 {.

7

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.

8

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.

9

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.

10

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.

11

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.

12

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

Was this helpful?