Budibase/budibase · error · HTTPError

channel.provider is required

Error message

channel.provider is required

What it means

webhookChat requires chat.channel.provider to identify which external channel (Slack, MS Teams, etc.) the message arrived on; it is used to build the session id (`${provider}:${chatId}`) and tracking. If channel or channel.provider is absent the request is rejected with HTTP 400 after agent validation.

Source

Thrown at packages/server/src/api/controllers/ai/chatConversations.ts:470

export async function webhookChat({
  chat,
  user,
  onAssistantStream,
}: {
  chat: ChatConversationRequest
  user: ContextUser
  onAssistantStream?: (stream: WebhookAssistantStream) => Promise<void>
}): Promise<WebhookChatCompleteResult> {
  const agentId = chat.agentId
  if (!agentId) {
    throw new HTTPError("agentId is required", 400)
  }

  const agent = await sdk.ai.agents.getOrThrow(agentId)
  const provider = chat.channel?.provider
  if (!provider) {
    throw new HTTPError("channel.provider is required", 400)
  }
  const chatId = chat._id ?? docIds.generateChatConversationID()
  const sessionId = `${provider}:${chatId}`
  let trackingHandle: AgentRequestTrackingHandle
  const run = await prepareAgentChatRun({
    agent,
    agentId,
    chat,
    errorLabel: "webhook chat",
    sessionId,
    user,
    getRequestId: () => trackingHandle?.requestId,
  })
  const title = run.latestQuestion
    ? truncateTitle(run.latestQuestion)
    : chat.title

  const userId = user.globalId || user.userId || user._id || ""

View on GitHub (pinned to a81a902e9a)

Solutions

1. Include channel: { provider: AgentChannelProvider.<SLACK|MSTEAMS|...> } in the chat payload
2. Fix the channel integration so it populates provider when constructing webhook chat requests
3. Confirm the provider value matches a valid AgentChannelProvider enum member
4. Inspect the inbound webhook body to ensure the provider field is not stripped by middleware

Example fix

// before
await webhookChat({ chat: { agentId, _id: chatId }, user })
// after
await webhookChat({ chat: { agentId, _id: chatId, channel: { provider: AgentChannelProvider.SLACK } }, user })

if (!chat.channel?.provider) throw new Error("chat.channel.provider must be set for webhook chat")

function hasChannelProvider(chat: ChatConversationRequest): chat is ChatConversationRequest & { channel: { provider: AgentChannelProvider } } {
  return !!chat.channel && typeof chat.channel.provider === "string"
}

try {
  await webhookChat({ chat, user })
} catch (e) {
  if (e instanceof HTTPError && e.status === 400 && e.message === "channel.provider is required") {
    // inspect integration payload construction
  }
  throw e
}

When it happens

Trigger: An inbound webhook payload missing the channel object, or containing channel without a provider field — e.g. calling webhookChat directly with only { _id, agentId }, or an integration that builds the channel metadata incompletely.

Common situations: Custom webhook integrations that don't mimic the official Slack/Teams payload shape; a provider enum value not set when constructing the ChatConversationRequest; refactored integration code dropping the channel field; provider values removed/renamed in a version change.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Error getting status
• Unable to remove doc without a valid _id and _rev.
• Cannot store document without _id field.
• Configuration invalid. Must contain google clientID and clie
• Configuration invalid. Must contain clientID, clientSecret,

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/af551bf970777811. Report an issue: GitHub.