Budibase/budibase · error · HTTPError

Teams integration appId must be a valid UUID

Error message

Teams integration appId must be a valid UUID

What it means

This HTTP 400 error is thrown by validateMSTeamsIntegration in packages/server/src/sdk/workspace/ai/deployments/ms-teams.ts when the appId (Microsoft Teams app client ID) supplied for a Teams integration fails the isValidUUID check. Budibase requires Teams app IDs to be well-formed UUIDs because they correspond to Azure AD app registration client IDs. Any malformed ID is rejected before the integration is saved or deployed.

Source

Thrown at packages/server/src/sdk/workspace/ai/deployments/ms-teams.ts:59

    throw new HTTPError(
      "Teams integration is not configured for this agent",
      400
    )
  }

  const appId = integration.appId?.trim()
  const appPassword = integration.appPassword?.trim()
  const tenantId = integration.tenantId?.trim()

  if (!appId || !appPassword || !tenantId) {
    throw new HTTPError(
      "Teams integration requires appId (client ID) and appPassword (client secret value)",
      400
    )
  }

  if (!isValidUUID(appId)) {
    throw new HTTPError("Teams integration appId must be a valid UUID", 400)
  }

  return {
    appId,
    appPassword,
    tenantId,
  }
}

export const buildMSTeamsWebhookUrl = async (agentId: string) =>
  await shared.buildProviderWebhookUrl(AgentChannelProvider.MSTEAMS, agentId)

export const buildMSTeamsManifest = ({
  agent,
  messagingEndpointUrl,
  appPackageVersion,
}: {
  agent: Agent

View on GitHub (pinned to a81a902e9a)

Solutions

1. Open the Azure Portal > App registrations, find your bot registration and copy the exact 'Application (client) ID' (a hyphenated UUID like 12345678-1234-1234-1234-123456789012).
2. Paste the full client ID including hyphens into the appId field of the agent's msTeamsIntegration and retry.
3. If the ID has no hyphens, format it as a standard 8-4-4-4-12 UUID before saving.
4. Verify you are not confusing the Azure 'Object ID' with the 'Application (client) ID'; only the latter is valid here.

Example fix

// before
agent.msTeamsIntegration = { appId: "my-teams-bot", appPassword: "secret" }
// after
agent.msTeamsIntegration = {
  appId: "8f2a1c34-56b7-4c89-9d01-2e3f4a5b6c7d", // Azure App registration client ID
  appPassword: "secret"
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
if (!UUID_RE.test(msTeams.appId)) {
  throw new Error("appId must be the Azure AD Application (client) ID in UUID format")
}

const isUuid = (v: string | undefined): v is string =>
  typeof v === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)

try {
  await saveTeamsIntegration({ appId, appPassword })
} catch (e) {
  if (e instanceof HTTPError && e.message.includes("valid UUID")) {
    // surface: re-prompt user for the Azure Application (client) ID
  }
  throw e
}

When it happens

Trigger: Calling the MS Teams integration save/deploy path with agent.msTeamsIntegration.appId set to a non-UUID string (e.g. a bot name, a GUID without the hyphenated UUID format, an empty-looking placeholder, or a truncated copy-paste of the Azure app registration client ID).

Common situations: Developers copy the Azure AD app registration client ID with missing characters, paste the object ID instead of the application (client) ID, or hand-enter a Teams 'Microsoft App ID' that is not hyphen-formatted. Older bots or manually created manifests sometimes use non-UUID identifiers.

Related errors

• Teams integration must be provisioned before downloading the
• Teams integration is not configured for this agent
• Teams integration requires appId (client ID) and appPassword
• Error getting status
• Unable to remove doc without a valid _id and _rev.

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