Budibase/budibase · error · HTTPError

Teams integration must be provisioned before downloading the

Error message

Teams integration must be provisioned before downloading the app package

What it means

Thrown by allocateMSTeamsAppPackageVersion when a Teams app package is requested for an agent whose MSTeamsIntegration has no messagingEndpointUrl (missing, empty, or whitespace-only). The package download depends on a provisioned Teams integration that exposes the messaging endpoint; without it the library refuses with a 400.

Source

Thrown at packages/server/src/api/controllers/ai/agents.ts:275

    .replace(/[^a-z0-9._-]+/g, "-")
    .replace(/^-+|-+$/g, "")
  return safe || "agent"
}

const toSafeTeamsPackageName = (agent: Agent) =>
  `budibase-teams-${toSafeFilenameSegment(agent.name)}-package.zip`

const allocateMSTeamsAppPackageVersion = async (agentId: string) => {
  for (
    let attempt = 0;
    attempt < TEAMS_APP_PACKAGE_VERSION_RETRIES;
    attempt++
  ) {
    const agent = await sdk.ai.agents.getOrThrow(agentId)
    const messagingEndpointUrl =
      agent.MSTeamsIntegration?.messagingEndpointUrl?.trim()
    if (!messagingEndpointUrl) {
      throw new HTTPError(
        "Teams integration must be provisioned before downloading the app package",
        400
      )
    }

    sdk.ai.deployments.MSTeams.validateMSTeamsIntegration(agent)

    const currentVersion =
      agent.MSTeamsIntegration?.appPackageVersion ||
      INITIAL_TEAMS_APP_PACKAGE_VERSION
    const appPackageVersion = semver.inc(currentVersion, "patch")
    if (!appPackageVersion) {
      throw new HTTPError("Invalid Teams app package version", 500)
    }

    try {
      const updatedAgent = await sdk.ai.agents.update({
        ...agent,

View on GitHub (pinned to a81a902e9a)

Solutions

Complete the Microsoft Teams integration provisioning so agent.MSTeamsIntegration.messagingEndpointUrl is set
Verify the agent config: agent.MSTeamsIntegration must exist with a non-empty trimmed messagingEndpointUrl
Re-run the Teams setup/provisioning step if a previous attempt failed, then retry the download
If the endpoint URL was cleared, restore it via the agent update API before downloading the package

Example fix

// before
GET /api/ai/agents/agent123/teams/app-package // integration not provisioned
// after
// 1. provision Teams integration first
await sdk.ai.agents.updateOperation(agentId, opId, {
  MSTeamsIntegration: { messagingEndpointUrl: "https://example.com/teams/msg" }
})
// 2. then download the package
GET /api/ai/agents/agent123/teams/app-package

Defensive patterns

Strategy: validation

Validate before calling

function canDownloadTeamsPackage(agent) {
  return Boolean(agent?.MSTeamsIntegration?.messagingEndpointUrl?.trim())
}
if (!canDownloadTeamsPackage(agent)) {
  throw new Error("Provision the Teams integration before downloading the app package")
}

Type guard

function isTeamsProvisioned(agent) {
  return typeof agent?.MSTeamsIntegration?.messagingEndpointUrl === "string" &&
    agent.MSTeamsIntegration.messagingEndpointUrl.trim().length > 0
}

Try / catch

try {
  const pkg = await downloadMSTeamsAppPackage(agentId)
} catch (err) {
  if (err.status === 400 && /Teams integration must be provisioned/.test(err.message)) {
    await provisionMSTeamsIntegration(agentId)
    return downloadMSTeamsAppPackage(agentId)
  }
  throw err
}

Prevention

Gate the 'Download app package' UI action on the integration being fully provisioned
Verify provisioning webhooks actually persisted messagingEndpointUrl before exposing downloads
Re-run provisioning when the endpoint URL is empty or blanked
Monitor Teams provisioning failures so agents never sit in a half-configured state

When it happens

Trigger: Downloading the Teams app package for an agent before the Microsoft Teams integration was provisioned, after provisioning failed partway (URL never saved), or after the URL was cleared/blanked while the integration object still exists. The check retries via getOrThrow until attempts are exhausted but never succeeds without a URL.

Common situations: Admins clicking 'Download app package' in the builder before finishing Teams setup; Teams provisioning webhook failing silently so messagingEndpointUrl stays empty; API-driven flows that create the integration shell but skip the provisioning step; environment/region changes that invalidate a previously provisioned endpoint.

Related errors

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