{Debug} Teams Toolkit Prerequisites Checker
Teams Toolkit checks the following prerequisites during the debug process:
-
Node.js, applicable for the following project types:
Project type Node.js LTS version Notification Bot (Express) 18, 20 Notification Bot (Http Trigger / Timer Trigger) 18, 20 Command Bot 18, 20 Workflow Bot 18, 20 Dashboard Tab 18, 20 SSO-enabled Tab 18, 20 SPFx Tab 18 Tab 18, 20 Bot 18, 20 Message extension 18, 20 -
Microsoft 365 account with valid credentials, the Teams toolkit prompts you to sign in to Microsoft 365 account, if you haven't signed in.
-
Custom app uploading or sideloading for your developer tenant is turned on, if not then the debug terminates .
-
Ngrok binary version 2.3 is applicable for bot and message extension, if Ngrok isn't installed or the version doesn't match the requirement, the Teams toolkit installs Ngrok NPM package
[email protected]in~/.fx/bin/ngrok. The Ngrok binary is managed by Ngrok NPM package in/.fx/bin/ngrok/node modules/ngrok/bin.Note: Teams Toolkit downloads npm package [email protected] which contains NGROK v2.3.40. Customer must have a valid license to use NGROK software. Microsoft does not license use of the NGROK.
-
Azure Functions Core Tools version 4, if Azure Functions Core Tools is'nt installed or the version doesn't match the requirement, the Teams Toolkit installs Azure Functions Core Tools NPM package, azure-functions-core-tools@4 for Windows and for macOs in
~/.fx/bin/func. The Azure Functions Core Tools NPM package in~/.fx/bin/func/node_modules/azure-functions-core-tools/binmanages Azure Functions Core Tools binary. For Linux, the debug terminates. -
.NET Core SDK version applicable for Azure Functions, if .NET Core SDK is'nt installed or the version doesn't match the requirement, the Teams Toolkit installs .NET Core SDK for Windows and MacOS in
~/.fx/bin/dotnet. For Linux, the debug terminates.The following table lists the .NET Core versions:
Platform Software Windows, macOs (x64), and Linux 3.1 (recommended), 5.0, 6.0 macOs (arm64) 6.0 -
Development certificate, if the development certificate for localhost is'nt installed for tab in Windows or macOS, the Teams toolkit prompts you to install it.
-
Azure Functions binding extensions defined in
api/extensions.csproj, if Azure Functions binding extensions is not installed, the Teams Toolkit installs Azure Functions binding extensions. -
NPM packages, applicable for tab app, bot app, message extension app, and Azure Functions. If NPM is'nt installed, the Teams Toolkit installs all NPM packages.
-
Bot and message extension, the Teams Toolkit starts Ngrok to create an HTTP tunnel for bot and message extension.
-
Ports available, if tab, bot, message extension, and Azure Functions ports are unavailable, the debug terminates.
The following table lists the ports available for components:
Component Port Tab 53000 Bot or message extension 3978 Node inspector for bot or message extension 9239 Azure Functions 7071 Node inspector for Azure Functions 9229
In case the Teams Toolkit fails to install prerequisites for you, you can manually install them by following the guidelines below.
Go to the official site to download and install the node.js. You may check for the node.js version requirements for differnet project types:
| Project type | Node.js LTS version |
|---|---|
| Notification Bot (Express) | 18, 20 |
| Notification Bot (Http Trigger / Timer Trigger) | 18, 20 |
| Command Bot | 18, 20 |
| Workflow Bot | 18, 20 |
| Dashboard Tab | 18, 20 |
| SSO-enabled Tab | 18, 20 |
| SPFx Tab | 16 |
| Tab | 18, 20 |
| Bot | 18, 20 |
| Message extension | 18, 20 |
Note: Please restart all your Visual Studio Code instances after the installation is finished.
Go to the official website to download and install the supported version:
| Platform | .NET versions |
|---|---|
| Windows, macOS (x64), Linux | .NET Core 3.1 SDK (recommended), .NET 5.0 SDK, .NET 6.0 SDK |
| macOS (arm64) | .NET 6.0 SDK |
Note: Please restart all your Visual Studio Code instances after the installation is finished.
Go to the official website to install the Azure Functions Core Tools v4.
Note: Please restart all your Visual Studio Code instances after the installation is finished.
Go to the official website to install the Bicep CLI v4.
Note: Please restart all your Visual Studio Code instances after the installation is finished.
Cannot find Node.js. Go to https://nodejs.org/about/releases/ to install Node.js.
As the Teams Toolkit project is implemented by Node.js, it's required to install the npm pacakges and run the project in local.
To resolve this, please refer to How to install Node.js? to install Node.js.
Node.js (node_version) is not in the supported version list (v18, v20).
When Azure is selected as the hosting type and the project does not contain Azure Functions, only LTS versions (v18 and v20) of Node.js are supported by Teams Toolkit currently, please make sure the installed Node.js meets this requirement. In addition, Node v16 (LTS) would be recommended to be installed.
To resolve this, please refer to How to install Node.js? to install the supported version of Node.js.
Node.js (node_version) is not in the supported version list (v18, v20).
When Azure is selected as the hosting type and the project contains Azure Functions, only LTS versions (v18 and v20) of Node.js are supported by Teams Toolkit currently, please make sure the installed Node.js meets this requirement. In addition, Node v16 (LTS) would be recommended to be installed.
To resolve this please refer to How to install Node.js? to install the supported version of Node.js.
Node.js (node_version) is not in the supported version list (v18 for SPFx v1.20.*).
The SharePoint Framework v1.20.* is supported on the following Node.js versions:
- Node.js v18 (Hydrogen)
And the latest version of Node.js LTS v18 would be recommended to be installed. For details, please refer to this document.
To resolve this please refer to How to install Node.js? to install the supported version of Node.js.
Failed to install .NET Core SDK (v3.1). Install .NET Core SDK (v3.1) manually and restart Visual Studio Code.
It might be caused by timeout issue (longer than 3 minutes), the process to install .NET SDK is killed, or other unknown issues.
To resolve this, please follow below instrucntion:
-
Retry the operation (debugging or Function app deployment).
-
Please refer to the guide to install
.NET SDKmanually.
Note: For M1 Mac users, currently neither
.NET 5.0 SDKor.NET Core 3.1 SDKsupports M1 Mac (see this GitHub issue).
Cannot find .NET Core SDK (v3.1 or v5.0).
To resolve this issue, please refer to the guide to install .NET SDK manually.
NETSDK1045: The current .NET SDK does not support 'newer version' as a target.
To resolve this issue, please refer to the guide to check your global.json file in the root folder in your project and up the directory chain to the root of the volume, since it can be anywhere in the folder structure. If it contains an SDK version, delete the sdk node and all its children, or update it to the desired newer .NET Core version (.NET 5 or .NET Core 3.1 ).
The global.json file is not required, so if it doesn't contain anything other than the sdk node, you can delete the whole file.
Failed to install [email protected]. Install [email protected] manually.
Since Bot and Message extension require public endpoint for communication, Teams Toolkit by default uses a built-in ngrok to create a tunnel connection forwarding localhost address to public address.
To resolve this issue, see How to use my own bot messaging endpoint to start local tunnel and set messaging endpoint manually.
Start from Teams Toolkit (>= 4.1.0), it generates new tasks that can be customized in
tasks.jsonfile.
For project created by Teams Toolkit (<= 4.0.6), if you prefer to manage some or all of the Teams app development prerequisites your self, you can use Visual Studio Code settings (Visual Studio Code Settings -> Teams Toolkit -> Prerequisite Check) to diasable the prerequisite checker. To open your user and workspace settings, use the following Visual Studio Code menu command:
- On Windows/Linux - File > Preferences > Settings > Extensions > Teams Toolkit
- On macOS - Code > Preferences > Settings > Extensions > Teams Toolkit
For CLI, you should run command as follows:
- Node.js:
teamsfx config set validate-node off - .NET SDK:
teamsfx config set validate-dotnet-sdk off - Azure Functions Core Tools:
teamsfx config set validate-func-core-tools off - Ngrok:
teamsfx config set validate-ngrok off - Development Certificate:
teamsfx config set trust-development-certificate off - Bicep CLI: Set
TEAMSFX_BICEP_ENV_CHECKER_ENABLE=falseto your environment variables.
If this document cannot solve the issue you met, please click here to submit an issue on GitHub and attach the log from Visual Studio Code output channel named Teams Toolkit.