When building conversational apps or screen-based flows using a declarative schema, you might come across the following error:

INVALID_NAVIGATE_ACTION_PAYLOAD
Fields in the navigation action payload are missing in the next screen’s data model.

Fixing it is usually just a matter of syncing your payload with the data model of the next screen. Get this right, and your app's navigation will be error free.

Read the complete blog to understand:

  • What this error means

  • Why it occurs

  • How to fix it with a working example

What Does This Error Mean?

In frameworks that use screen navigation (like Google App Actions or other UI schema-based platforms), when you navigate from one screen to another and pass data via payload, the destination screen (next screen) must declare those fields in its data model.

If it doesn't, the system throws this error:

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

What’s Going Wrong?

Here’s the problematic snippet:

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

You’re trying to send the value "name": "some name" from FIRST_SCREEN to SECOND_SCREEN using the payload. But in SECOND_SCREEN, the data block is empty.

So the system says:

“Hey, you're sending me a name, but I don't see it defined in the next screen's data model!”

How to Fix It?

You need to define the expected fields in the data model of the destination screen (SECOND_SCREEN) so that it can receive and use them.

Fixed Example:

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

Now, the SECOND_SCREEN is ready to accept the name field and use it however you want (e.g., displaying it in the UI or triggering logic).

Quick Tips

  • Always declare fields you pass in the payload inside the data section of the next screen.

  • Match field names exactly — spelling and case matter.

  • Avoid passing unnecessary data if it’s not used on the next screen.

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