# 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](/rcs-experience-schema/rcs-experience-schema/quick-start.md) 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://playbook.nativemsg.com/rcs-experience-schema/guides/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.