Budibase/budibase · error · HTTPError

Workspace context is required

Error message

Workspace context is required

What it means

Chat streaming requests must run inside a workspace (app) context. context.getWorkspaceId() derives this from the request (headers, subdomain, or URL). When absent — e.g. calls outside an app context — the server throws HTTP 400 'Workspace context is required'.

Source

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

  if (agentId) {
    chat.agentId = agentId
  }
  if (chatConversationId && chatConversationId !== "new") {
    chat._id = chatConversationId
  }
}

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)
  }

View on GitHub (pinned to a81a902e9a)

Solutions

  1. Include the workspace/app id in the request (x-budibase-app-id header or app-scoped URL)
  2. Call the app API endpoint rather than the global/worker endpoint
  3. Verify proxies don't strip Budibase context headers

Example fix

// before
fetch('http://localhost:4002/api/ai/chat/agent_1/stream', {...})
// after
fetch('http://localhost:4001/api/ai/chat/agent_1/stream', {
  headers: { 'x-budibase-app-id': appId, ...auth }
})
Defensive patterns

Strategy: validation

Validate before calling

if (!appId) {
  throw new Error("Workspace/app id is required for chat streaming")
}

Try / catch

try {
  await streamChat(body)
} catch (e) {
  if (e.status === 400 && String(e.message).includes("Workspace context is required")) {
    // add the x-budibase-app-id header and retry
  }
}

Prevention

When it happens

Trigger: Calling the chat stream endpoint without the workspace-scoped URL/headers (e.g. hitting the worker/global API directly, or missing appId header).

Common situations: Scripted API calls omitting the 'x-budibase-app-id' header; using the global/worker port instead of the app API; reverse proxy stripping headers.

Related errors

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