While building WhatsApp flows with data channel JSON (version 2.1), you might come across this error:

INVALID_ROUTING_MODEL: Missing direct route from screen '${source}' to screen '${destination}' in the routing model, while it exists in the navigate screen action of screen '${source}'.

This is a routing mismatch error—and it’s easier to fix than it sounds. Let’s walk through what causes it and how to resolve it.

What This Error Means?

When your screen layout includes a navigate action (like a button that takes the user to another screen), that navigation must also be declared in the routing_model.

If the action exists in your layout but the route is missing from the routing_model, WhatsApp throws this error.

Example That Triggers the Error

{
  "version": "2.1",
  "routing_model": {
    "FIRST_SCREEN": []
  },
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        "children": [
          {
            "type": "Footer",
            "on-click-action": {
              "name": "navigate",
              "next": {
                "type": "screen",
                "name": "SECOND_SCREEN"
              }
            }
          }
        ]
      }
    },
    {
      "id": "SECOND_SCREEN"
    }
  ]
}

In this JSON:

  • FIRST_SCREEN has a button that navigates to SECOND_SCREEN

  • But the routing_model doesn't declare that route

  • Result: INVALID_ROUTING_MODEL error

How to Fix It?

To fix the error, you need to add the missing route to the routing_model.

Corrected Example

{
  "version": "2.1",
  "routing_model": {
    "FIRST_SCREEN": ["SECOND_SCREEN"]
  },
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        "children": [
          {
            "type": "Footer",
            "on-click-action": {
              "name": "navigate",
              "next": {
                "type": "screen",
                "name": "SECOND_SCREEN"
              }
            }
          }
        ]
      }
    },
    {
      "id": "SECOND_SCREEN"
    }
  ]
}

Now the routing model matches the actual navigation, and the flow is valid.

Why This Happens?

The routing model acts like a map of possible paths. Even if the navigate action exists visually in the layout, WhatsApp still checks the routing_model for an explicit connection between screens.

This double-checking:

  • Keeps flows predictable

  • Helps validate logic ahead of time

  • Prevents broken screen transitions at runtime

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