Budibase/budibase · error · HTTPError

Preview mode requires a development workspace

Error message

Preview mode requires a development workspace

What it means

Preview chat streaming is restricted to development (draft) workspaces. isDevWorkspaceID(workspaceId) rejects requests against a published/deployed workspace id, throwing HTTP 400 'Preview mode requires a development workspace'.

Source

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

  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,
      roleId: previewRole._id,
    }
  }

  const agentId = chat.agentId
  if (!agentId) {
    throw new HTTPError("agentId is required", 400)
  }

View on GitHub (pinned to a81a902e9a)

Solutions

1. Use the development/draft workspace id (appDevId) in the request
2. Obtain the dev app id from the builder UI or the app metadata API
3. Point scripts at the dev workspace rather than the published one

Example fix

// before
headers: { 'x-budibase-app-id': publishedAppId }
// after
headers: { 'x-budibase-app-id': devAppId }

if (!isDevId(appId)) {
  throw new Error("Preview chat requires the development (draft) app id")
}

try {
  await streamChat(body)
} catch (e) {
  if (e.status === 400 && String(e.message).includes("development workspace")) {
    // swap in the dev app id and retry
  }
}

When it happens

Trigger: Sending isPreview: true to the chat stream endpoint while the resolved workspaceId is a published app id (not the dev/draft id).

Common situations: Client using the production appId with preview flags; testing after the app was published and the dev id changed; hard-coded app ids in scripts.

Related errors

• Workspace context is required
• Invalid bookmark query
• Invalid limit query
• Limit query must be between 1 and 100
• Invalid ${queryName} query

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