# 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`.

{% tabs %}
{% tab title="Invalid" %}

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

Missing: `name`
{% endtab %}

{% tab title="Corrected" %}

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

{% endtab %}
{% endtabs %}

***

### 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`.

{% tabs %}
{% tab title="Invalid" %}

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

Missing: `intents`
{% endtab %}

{% tab title="Corrected" %}

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

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

```json
{
  "send": {
    "message": {}
  }
}
```

{% endtab %}

{% tab title="Corrected" %}

```json
{
  "send": {
    "message": {
      "text": "Welcome to Acme Support!"
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

```json
{
  "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.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "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"
        }
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

```json
{
  "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.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "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.
{% endtab %}
{% endtabs %}

***

### 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`.

{% tabs %}
{% tab title="Invalid" %}

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

Missing `title` for `weburl` button.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "buttons": [
    {
      "type": "weburl",
      "title": "Shop now",
      "payload": "https://shop.acme.com"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

***

### 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`.

{% tabs %}
{% tab title="Invalid" %}

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

Missing `title` for `text` quick reply.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "quickReplies": [
    {
      "type": "text",
      "title": "Track my order",
      "payload": "track_order"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

***

### `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.

{% tabs %}
{% tab title="Invalid" %}

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

Missing `data` and `content`.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "waitFor": {
    "data": "text",
    "content": "userInput",
    "timeout": "5m"
  }
}
```

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

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

`user-email` contains a hyphen — not permitted.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "waitFor": {
    "data": "text",
    "content": "userEmail"
  }
}
```

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

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

`2ndAddress` starts with a digit — not permitted.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "assignAttributes": {
    "attributes": [
      {
        "attributePath": "secondaryAddress",
        "value": "123 Main St"
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

***

### `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.

{% tabs %}
{% tab title="Invalid" %}

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

`method` is `POST` but `content` is absent.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "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"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

### `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.

{% tabs %}
{% tab title="Invalid" %}

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

Name is 111 characters — maximum is 100.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "name": "Acme Customer Support Bot v2",
  "workflows": []
}
```

{% endtab %}
{% endtabs %}

***

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

{% tabs %}
{% tab title="Invalid" %}

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

{% endtab %}

{% tab title="Corrected" %}

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

{% endtab %}
{% endtabs %}

***

### 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`.

{% tabs %}
{% tab title="Invalid" %}

```json
{
  "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`.
{% endtab %}

{% tab title="Corrected" %}

```json
{
  "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"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

***

## Debugging Checklist

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

{% stepper %}
{% step %}

### 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](https://playbook.nativemsg.com/rcs-experience-schema/rcs-experience-schema/quick-start) for complete examples. Fix all reported errors before proceeding.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### Confirm carousel lengths

Carousels MUST have 2–10 items. 
{% endstep %}

{% step %}

### 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).
{% endstep %}

{% step %}

### 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 `{`.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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. 
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}