If you’re designing a screen-based UI flow using a declarative schema (like in conversational or visual app builders), you may encounter this error:

INVALID_NAVIGATE_ACTION_PAYLOAD
Following fields are expected in the next screen's data model but missing in payload: [fieldNames]

Let’s break down:

  • What this error means

  • Why it happens

  • How to fix it with an example

What Does the Error Mean?

This error shows up when:

  • You're navigating from one screen to another using an action

  • The next screen's data model expects some fields

  • But you didn’t send those fields in the payload of the navigation action

In other words, the next screen is asking for data you didn’t give it.

The Problem

Here's the problematic schema:

{
  "version": "2.1",
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        ...
        {
          "on-click-action": {
            "name": "navigate",
            "next": {
              "type": "screen",
              "name": "SECOND_SCREEN"
            },
            "payload": {}
          }
        }
      }
    },
    {
      "id": "SECOND_SCREEN",
      "data": {
        "name": { "type": "string" }
      },
      "layout": {
        ...
      }
    }
  ]
}

The issue:

  • SECOND_SCREEN expects a field called name in its data model.

  • But when navigating from FIRST_SCREEN, the payload is empty.

The system complains:

“You're taking me to SECOND_SCREEN, but you didn't give me the data I need!”

The Fix

To resolve this, you need to include all required data fields from the next screen’s data model in the payload of the navigate action.

Fixed Example

{
  "version": "2.1",
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        ...
        {
          "on-click-action": {
            "name": "navigate",
            "next": {
              "type": "screen",
              "name": "SECOND_SCREEN"
            },
            "payload": {
              "name": "John Doe"
            }
          }
        }
      }
    },
    {
      "id": "SECOND_SCREEN",
      "data": {
        "name": { "type": "string" }
      },
      "layout": {
        ...
      }
    }
  ]
}

Now, when the user navigates to SECOND_SCREEN, the required name value is provided.

For more troubleshooting tips related to WhatsApp Business API, check out heltar.com/blogs.