Skip to content

Teams Agent Preflight FAQ

Common failures from preflight.sh / preflight.ps1 and how to fix them.

Prerequisites

python3 / python — not installed

Download and install Python 3.11+.

After installing on Windows, if python still isn't found, go to Settings → Apps → Advanced app settings → App execution aliases and disable the python.exe store alias.

node — not installed

Download and install Node.js 18 or later from nodejs.org/en/download.

az — not installed

Install the Azure CLI: aka.ms/installazurecli.

Verify with: 

az --version

teamsapp — not installed

Install the Teams App CLI: 

npm install -g @microsoft/teamsapp-cli@3.1.0

If npm is not found, install Node.js first (see above).

PowerShell policy — Restricted (Windows only)

Your execution policy is blocking scripts. Run: 

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Then re-run preflight.

Auth

Azure login — FAIL

You are not signed in to Azure CLI. Run: 

az login --use-device-code
Follow the device-code prompt in your browser.

Teams/M365 login — FAIL

You are not signed in to the Teams App CLI. Run: 

teamsapp auth login m365
A browser window will open for Microsoft 365 authentication.

Azure tenant — mismatch

Your active Azure subscription belongs to a different tenant than the one configured for this agent.

  1. List your subscriptions: az account list --output table
  2. Switch to the correct one: az account set --subscription <subscription-id>
  3. Re-run preflight.

Permissions

Azure RBAC — need Contributor or Owner

Your account does not have Contributor or Owner on the target subscription.

Ask your Azure administrator to grant you one of these roles:

  • Contributor — sufficient for most deployments
  • Owner — required if you also need to manage role assignments

Navigate to Azure Portal → Subscriptions → [your subscription] → Access control (IAM) → Add role assignment.

Entra ID app registration — need Application Administrator

Your account does not have the Application Administrator (or Global Administrator) directory role in Entra ID.

Ask your Entra administrator to assign you the Application Administrator role:

Azure Portal → Microsoft Entra ID → Roles and administrators → Application Administrator → Add assignments

Teams publish (admin role) — need Teams Administrator

Publishing the Teams app to your org catalog requires the Teams Administrator (or Global Administrator) role.

Ask your Microsoft 365 administrator to assign you the Teams Administrator role:

Microsoft 365 admin center → Roles → Role assignments → Teams Administrator

Entra ID / Teams — could not query directory roles

The preflight script could not reach the Microsoft Graph API to check your roles. Common causes:

  • You are not signed in to Azure CLI (az login --use-device-code)
  • Your account lacks the Graph Directory.Read.All permission
  • A conditional-access policy is blocking the request
  • Transient network or token issue

Re-run az login --use-device-code, then re-run preflight. If the error persists, contact your Azure administrator.