Budibase/budibase · error · Error

Agent execution context is required

Error message

Agent execution context is required

What it means

When the selected agent operation defines escalation recipients, prepareAgentChatRunInternal installs the real escalate tool, which requires the executionContext (built earlier from workspace/tenant ids) to stamp escalation payloads with workspace, tenant, agent and operation ids. If executionContext is undefined (e.g. the run is a resume without a prepared execution context, or context creation was skipped) but the operation demands escalation, this guard throws.

Source

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

  }

  // The escalate tool exists only in the old mode: stripped when ESCALATION
  // is off, and when AI_TOOL_ESCALATION is on (gating replaces it outright).
  if (
    tools.escalate &&
    (escalationGateContext ||
      !(await features.isEnabled(FeatureFlag.ESCALATION)))
  ) {
    delete tools.escalate
  }

  if (tools.escalate) {
    const recipients = selectedOperation?.escalation?.recipients
    if (selectedOperation && recipients?.length) {
      // Always the real tool, on resumes too. A resumed run must still be
      // able to raise a genuinely new escalation.
      if (!executionContext) {
        throw new Error("Agent execution context is required")
      }
      tools.escalate = createEscalateTool({
        agentId,
        operationId: selectedOperation.id,
        sessionId,
        recipients,
        delayMs:
          (selectedOperation.escalation?.delay ??
            DEFAULT_ESCALATION_DELAY_SECONDS) * 1000,
        channel: chat?.channel,
        userId: user?._id,
        getMessages: () => modelMessages,
        getRequestId: () => getRequestId?.(),
        executionPrincipal: ToolExecutionPrincipal.ADMIN,
        executionContext,
      })
    }

View on GitHub (pinned to a81a902e9a)

Solutions

1. Ensure resumed runs rebuild the execution context (re-run prepareAgentRunContext) before prepareAgentChatRunInternal
2. Pass the executionContext produced by prepareAgentChatRun through to resume calls instead of dropping it
3. If the resume path legitimately has no execution context, either remove escalation recipients from the operation or reject the resume earlier with a clearer error
4. Call prepareAgentChatRun (public wrapper) rather than the internal function directly

Example fix

// before
await prepareAgentChatRunInternal({ sessionId, resume: true })
// after
const executionContext = await prepareAgentRunContext({ agentId, routingDecision })
await prepareAgentChatRunInternal({ sessionId, resume: true, executionContext })

if (selectedOperation?.escalation?.recipients?.length && !executionContext) {
  // rebuild context before preparing the run
  executionContext = await prepareAgentRunContext({ agentId, routingDecision })
}

try {
  run = await prepareAgentChatRun(params)
} catch (err) {
  if (err.message === "Agent execution context is required") {
    // rebuild execution context and retry the run preparation
  } else { throw err }
}

When it happens

Trigger: Resuming an agent chat run (e.g. after escalation resolution) where selectedOperation has escalation.recipients configured but executionContext was not rebuilt/passed into prepareAgentChatRunInternal; or a run path where the operation routing produced an operation but the execution-context preparation step was skipped or failed silently earlier.

Common situations: Resumed sessions whose stored state lacks the execution context; operations edited after a run started so escalation recipients were added but the resume path predates context preparation; calling the internal prepare function directly (not via prepareAgentChatRun) without supplying execution context.

Related errors

• escalation gate: missing workspace context
• Agent not found
• Operation not found
• workspaceId is required
• Cannot create an operation escalation with no recipients

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