What causes "Escalation context doc not found: ${escalationId}" in Budibase/budibase?

Verify the escalation context doc is created before recordEscalationRaised is invoked with its ID

Escalation context doc not found: ${escalationId}

Error message

Escalation context doc not found: ${escalationId}

What it means

recordEscalationRaised loads an escalation context document by ID before recording an escalation-raised action for an agent request. If no document exists for escalationId, it throws Error(`Escalation context doc not found: ${escalationId}`) instead of recording an escalation against missing data.

Source

Thrown at packages/server/src/sdk/workspace/ai/agentRequests/crud.ts:324

      throw err
    }
  }
}

async function recordEscalationRaised({
  requestId,
  sessionId,
  escalationId,
}: {
  requestId: string
  sessionId: string
  escalationId: string
}): Promise<void> {
  const timestamp = nowIso()

  const doc = await getContextDoc(escalationId)
  if (!doc) {
    throw new Error(`Escalation context doc not found: ${escalationId}`)
  }
  const recipients = await Promise.all(
    (doc.recipients ?? []).map(async recipient => ({
      type: recipient.type,
      label: await resolveRecipientLabel(recipient),
    }))
  )

  await appendAction(
    requestId,
    {
      type: "escalation_raised",
      escalationId,
      recipients,
      sessionId,
    },
    timestamp
  )

View on GitHub (pinned to a81a902e9a)

Solutions

Verify the escalation context doc is created before recordEscalationRaised is invoked with its ID
Check you are using the same workspace/environment DB for both the write and read
Catch the error and skip/defer the escalation recording, or recreate the context doc

Example fix

// before
const doc = await getContextDoc(escalationId)
if (!doc) {
  throw new Error(`Escalation context doc not found: ${escalationId}`)
}
// after
const doc = await getContextDoc(escalationId)
if (!doc) {
  console.warn(`Skipping escalation ${escalationId}: context doc missing`)
  return
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await recordEscalationRaised({ requestId, escalationId })
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Escalation context doc not found")) {
    // recreate the escalation context doc or skip recording this escalation
  }
}

Prevention

Create the escalation context doc before raising the escalation and pass that exact ID
Keep write and read in the same workspace/environment DB
Avoid reusing escalation IDs across retries without verifying the doc exists

When it happens

Trigger: Calling recordEscalationRaised (via recordToolCall) with an escalationId whose context doc was never created, was already deleted, or belongs to a different workspace DB.

Common situations: The escalation context doc expired or was cleaned up before the escalation was recorded; a typo/stale ID passed between automation steps; the doc was written to dev DB but read from prod (or vice versa).

Related errors

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