Budibase/budibase · error · HTTPError

Preview mode is required

Error message

Preview mode is required

What it means

The chat stream endpoint only supports preview mode: body.isPreview must be exactly true. Non-preview (published-app runtime) chat streaming is not allowed through this route, so any other value throws HTTP 400 'Preview mode is required'.

Source

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

const resolveChatStreamRequest = async (
  ctx: UserCtx<ChatAgentRequest, void>
): Promise<ResolvedChatStreamRequest> => {
  const chat = ctx.request.body
  const userId = getGlobalUserId(ctx)
  applyChatStreamPathParams(chat, ctx.params)

  const workspaceId = context.getWorkspaceId()
  if (!workspaceId) {
    throw new HTTPError("Workspace context is required", 400)
  }
  const isBuilderOrAdmin = usersSdk.users.isAdminOrBuilder(
    ctx.user,
    workspaceId
  )

  if (chat.isPreview !== true) {
    throw new HTTPError("Preview mode is required", 400)
  }

  if (!isBuilderOrAdmin) {
    throw new HTTPError("Forbidden", 403)
  }

  if (!isDevWorkspaceID(workspaceId)) {
    throw new HTTPError("Preview mode requires a development workspace", 400)
  }

  let user = ctx.user
  if (chat.previewRoleId) {
    const previewRole = await roles.getRole(chat.previewRoleId)
    if (!previewRole?._id) {
      throw new HTTPError("Preview role not found", 400)
    }
    user = {
      ...ctx.user,

View on GitHub (pinned to a81a902e9a)

Solutions

1. Set isPreview: true (boolean) in the request body
2. If you need chat in a published app, use the appropriate production chat route instead of this preview stream endpoint
3. Fix client serialization so isPreview is a real boolean

Example fix

// before
{ "agentId": "agent_1", "isPreview": "true" }
// after
{ "agentId": "agent_1", "isPreview": true }

if (body.isPreview !== true) {
  throw new Error("Chat stream requires isPreview: true (boolean)")
}

const isPreviewRequest = (b: { isPreview?: unknown }): b is { isPreview: true } =>
  b.isPreview === true

try {
  await streamChat({ ...body, isPreview: true })
} catch (e) {
  if (e.status === 400 && String(e.message).includes("Preview mode is required")) {
    // fix the isPreview flag before retrying
  }
}

When it happens

Trigger: POST to the chat stream endpoint with body.isPreview false, undefined, or a truthy-but-not-true value like "true" (string) or 1.

Common situations: Integrations built before the preview-only restriction; clients serializing booleans as strings; attempting to run agent chat in a published app via this endpoint.

Related errors

• Invalid bookmark query
• Invalid limit query
• Limit query must be between 1 and 100
• Invalid ${queryName} query
• Invalid environment query

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