Budibase/budibase · error · Error

Workspace context is required

Error message

Workspace context is required

What it means

prepareAgentRunContext builds an AgentExecutionContext (tenantId, workspaceId, agentId, operationId) when tool-level security routing has selected an operation and there is a requester. Since the execution context is what tools use to scope permissions, a missing workspace id makes it impossible to build a valid context, so the runtime throws immediately.

Source

Thrown at packages/server/src/sdk/workspace/ai/agents/agentRuntime.ts:415

    sessionId,
    span,
    agentId
  )
  const routingDecision = await selectOperationForRun({
    agent,
    sessionId,
    latestQuestion,
    operationId,
    llm,
  })
  const toolSecurityEnabled = await features.isEnabled(
    FeatureFlag.AI_AGENT_TOOL_SECURITY
  )
  let executionContext: AgentExecutionContext | undefined
  if (routingDecision.operation && requester) {
    const workspaceId = context.getWorkspaceId()
    if (!workspaceId) {
      throw new Error("Workspace context is required")
    }
    executionContext = {
      tenantId: context.getTenantId(),
      workspaceId,
      agentId,
      operationId: routingDecision.operation.id,
      conversationId: sessionId,
      requester,
    }
  }
  const promptAndTools = await buildPromptAndTools(
    agent,
    routingDecision.operation,
    {
      ...buildPromptOptions,
      fallbackPromptInstructions:
        routingDecision.action === "summarize_operations"
          ? buildOperationsSummaryPrompt(getLiveOperations(agent))

View on GitHub (pinned to a81a902e9a)

Solutions

1. Run the agent within a workspace context (context.withWorkspace or the standard workspace-scoped route/middleware)
2. Check how the run was triggered; only workspace-scoped requests can execute secured operations
3. In tests, initialize workspace context before calling prepareAgentRunContext / the chat run
4. Verify workspace resolution upstream (app/workspace id parsing) if the request does include a workspace identifier

Example fix

// before
const run = await prepareAgentChatRun(params)
// after
await context.doInWorkspaceContext(appId, async () => {
  const run = await prepareAgentChatRun(params)
})

import context from "@budibase/backend-core/context"
if (!context.getWorkspaceId()) {
  throw new Error("Agent runs require a workspace-scoped request")
}

try {
  await prepareAgentChatRun(params)
} catch (err) {
  if (err.message === "Workspace context is required") {
    // re-invoke within a workspace context
  } else { throw err }
}

When it happens

Trigger: Invoking the agent runtime with a routingDecision that has an operation and a non-null requester while context.getWorkspaceId() is undefined — e.g. an agent run triggered outside a workspace-scoped request (script, job, or un-scoped API call), or workspace context middleware not applied to the route.

Common situations: Hitting the agent endpoint without workspace scoping in the URL/headers; calling runtime functions from tests without context setup; running an agent via a background worker that forgot to restore workspace context; tenant/workspace resolution failing upstream (invalid app id).

Related errors

• workspaceId is required
• workspaceId is required
• Could not determine workspace for Project import
• Invalid object store key: path traversal is not allowed.
• Only HTTP(S) URLs are allowed.

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