FAQ and troubleshooting

For questions and feedback, visit the ST Community. Include the selected editor and agent, installed context versions, and the exact error. Remove credentials and private project information before posting.

How should I work with an AI coding assistant?

Treat the assistant as a development aid, not as the authority for project or device behavior. Results vary with the assistant, model, available context, and the details in the request.

For a focused request, identify the exact target and outcome. For example, name the NUCLEO-C562RE board, the STM32C562RET6 MCU, the peripheral, and the behavior expected. Include only the relevant source files, configuration, error messages, and constraints.

Before changes, ask the assistant to explain its proposed steps and which files or tools it expects to use. Review the changes and authorize software installation, builds, generated-file updates, and device operations before they run. Keep passwords, tokens, private keys, and other credentials out of prompts and project files.

Verify the result independently. Inspect project configuration and generated source, run the project’s build and tests, and check behavior on the target board where applicable. A plausible explanation or successful generation does not prove that the project is correct. State any missing evidence and review Known limitations before relying on an uncertain answer.

Why use the toolkit?

A general-purpose model does not know the current project configuration or which STM32 sources apply. The toolkit gives the agent access to official documentation, selected software examples, and STM32Cube tool workflows. The installer resolves declared tool dependencies and records each project’s context versions. Project files remain available for inspection and manual work in STM32Cube tools. Review the agent’s sources and verify its results.

STM32Cube contexts connect the agent to sources and tools

How does custom installation differ from setup?

Custom installation separates three levels of control:

• Machine: cube agentic-ai machine-bootstrap installs context bundles on the machine. It does not deploy contexts into a project.

• Project: cube agentic-ai project-deploy-installed selects installed contexts and services to deploy into a project.

• Dependencies: cube agentic-ai doctor <project-folder> --fix checks deployed services and resolves dependencies the installer can manage. Complete reported manual prerequisites separately.

cube agentic-ai setup combines these operations for a new project and abstracts their sequencing. Both paths report data.readiness and data.nextSteps. See Choose your installation for the installation choices and the installation guide in SEE ALSO for commands and options.

How can I use an existing venv?

For a new project, pass the existing venv’s Python executable to cube agentic-ai setup with --python "<absolute executable path>". Use the path ending in Scripts/python.exe on Windows or bin/python on macOS and Linux. --python venv instead selects the eSW bundle-local environment, not an existing user-created venv.

The custom installation path cannot explicitly select an existing venv through doctor in the current release. doctor has no --python option and uses auto for context checks. Activating a venv before running doctor is not a supported workaround for selecting where eSW packages are installed:

• With a saved eSW Python choice, doctor reuses that choice. A choice explicitly selected through setup --python is retained for later package checks and repair.

• Without a saved choice, eSW detects Python automatically. If package repair detects a virtual environment, it creates or reuses the bundle-local venv rather than installing into that detected environment.

Do not run setup on an already deployed project to change its Python choice. See How can I diagnose eSW Python setup? for detection and repair details.

A future release may add a --python option to doctor to allow explicit selection of an existing venv in the custom installation path. This option is not available in the current release.

What does doctor check?

cube agentic-ai doctor <project-folder> checks the requirements declared by deployed toolkit contexts. It reports whether required tools, Python packages, and declared VS Code extensions are present. Add --fix to resolve dependencies the installer can manage. Inspect data.readiness and data.nextSteps in the result.

doctor is not a general MCP or agent-host diagnostic tool. It does not validate arbitrary MCP JSON syntax or file placement, diagnose a server that fails to start, or check an agent’s runtime, credentials, or network policy. For those issues, inspect the selected agent’s MCP configuration and its own server status or startup logs. Do not put credentials in the chat or logs.

For example, to check and resolve the eSW Python packages in a deployed project, run:

cube agentic-ai doctor ./my-agentic-ai-project --bundles cube-agentic-ai-esw --fix

Why are dependencies missing after setup?

data.status: ALL_DEPLOYED confirms that the selected contexts were deployed. It does not guarantee that they are ready to use. Check data.readiness, data.requirements, and data.nextSteps for unresolved dependencies, manual prerequisites, or checks still to perform.

For example, omitting --install-vscode-extensions from setup leaves extension installation as a reported next step. Run cube agentic-ai doctor <project-folder> --fix to resolve supported requirements. Add --vscode-profile "<exact existing profile name>" to authorize installation of missing declared VS Code extensions in that profile. Without an explicit profile, doctor reports extension commands instead of installing them. Complete manual prerequisites, then rerun doctor. Do not rerun setup on the deployed project to repair dependencies.

How can I diagnose eSW Python setup?

The eSW context detects Python in this order: py -3, python3, then python on Windows. On macOS and Linux, it tries python3, then python. It uses the first candidate that runs as Python 3. That interpreter must be Python 3.10 or later. If the first candidate is older, the check reports it rather than trying a later command.

Run the detection commands in the same terminal that runs the installer. These commands show both the version and the executable path:

PowerShellbash or zsh

py -3 --version
py -3 -c "import sys; print(sys.executable)"
python3 --version
python3 -c "import sys; print(sys.executable)"
python --version
python -c "import sys; print(sys.executable)"

If the first detected Python is older than 3.10, correct the launcher or PATH so it finds a supported version, or create a new project with setup --python "<absolute path to Python 3.10 or later>". When detection finds a suitable Python, prefer setup --python venv. The bundle-local environment uses the detected Python as its base and is shared by projects using the same eSW bundle version.

Changing the system’s default Python does not update an existing bundle venv. It remains based on the compatible Python detected when it was created. The user or organization is responsible for refreshing the shared venv when a Python upgrade is required, including for security updates. Remove the installed eSW bundle version’s pybin/.venv directory, then run cube agentic-ai doctor <project> --bundles cube-agentic-ai-esw --fix for each affected deployed project configured to use venv. The command recreates the environment from the currently detected compatible Python and checks or installs the project’s required packages. All projects using the same eSW bundle version then share the refreshed environment.

For a package-install failure in an existing project, run the eSW doctor command above and inspect its requirement and fix results. doctor --fix reuses the Python choice saved when that project was created. If pip cannot reach its package index, check the organization’s proxy, certificate, mirror, and timeout settings, then retry. A failed pip install does not silently switch to another Python.

Where should contexts be installed?

Deploy contexts into the top-level folder of a project or workspace. Do not deploy them into the user home directory. This keeps context selection, configuration, and lock files project-scoped. See Supported IDEs and AI coding agents for the deployment layout and the installation guide for setup steps.

Why is a context unavailable?

The Build and DAP Debug contexts require the VS Code IDE target. They are not installed for Cursor or terminal-only targets. Check Supported IDEs and AI coding agents and the current list in Supported contexts and versions.

Why generate at the workspace root?

STM32CubeIDE for Visual Studio Code must discover the generated project before the Build and DAP Debug contexts can use it. Keep the STM32CubeMX2 project and generated build files in the top-level project folder opened in VS Code. Generating into a nested folder can prevent discovery. This is a requirement of that IDE workflow, not a general restriction on STM32CubeMX2 output paths.

For the project-folder requirements, see Supported IDEs and AI coding agents and the Build guide.

What do service IDs mean?

Interactive deployment lists services declared by each context bundle. Identifiers such as S1 are local to that context, not toolkit-wide names. Inspect the installed context’s service names and descriptions with:

cube cube-agentic-ai-esw --list-ai-services

For the embedded-software service mapping, see STM32Cube Embedded Software Context. For services already deployed into a project, run cube agentic-ai project-lock-show <project-folder>.

Do old bundle versions accumulate?

Yes. Installing or updating a bundle can leave earlier versions on the machine. Different projects can require different versions. Installing a new version does not require uninstalling the old one, and does not update existing project deployments. See Supported contexts and versions for project updates.

To inspect installed versions and remove a selected version, use:

cube bundle list
cube bundle remove <bundle-name>@<version>

Before removal, check project locks and dependent tools. Do not remove a version still needed by another project. Reinstalling a removed version can require network access. Removing a machine bundle does not remove its deployed project files. See the STM32CubeCLI documentation in SEE ALSO on STM32CubeCLI and project housekeeping for bundle lifecycle details.

Why did updating a bundle not update my project?

Machine installation and project deployment are separate. Updating a context on the machine does not change a project that already records an older version. Follow the project update steps in Supported contexts and versions.

Can the toolkit automatically build or debug with other IDEs?

No. The Build and DAP Debug contexts provide automated workflows only for STM32CubeIDE for Visual Studio Code. They do not automatically build or debug projects in STM32CubeIDE (the Eclipse-based IDE), IAR EWARM, or Keil MDK 5/6. STM32CubeIDE for Visual Studio Code is a separate product and workflow from STM32CubeIDE (Eclipse-based). Use each of those IDEs’ own build and debug workflows. Other toolkit contexts remain available where their documented target support allows them.

Why can the build or debug check fail in VS Code?

Confirm that the project is the workspace root and that STM32CubeIDE for Visual Studio Code has discovered it. Check the setup and debugger requirements in the Build and Debug guides.

What should I do when PowerShell shows ^U?

PowerShell 5.1 in the VS Code integrated terminal can display ^U when Ctrl+U is pressed. Use PowerShell 7.3 or later, or switch the integrated terminal to bash or zsh.

1. Install PowerShell 7.3 or later if it is not already installed.

2. In VS Code, open the Command Palette and run

   Terminal: Select Default Profile.

3. Select PowerShell (the PowerShell 7 profile), close the existing

   terminal, and create a new terminal.

4. Confirm the version with:

   $PSVersionTable.PSVersion
   

If ^U appears in the current command line, press Ctrl+C to cancel that input, then type the command again in the new terminal. Alternatively, select a bash or zsh profile from Terminal: Select Default Profile.

Why does MX2 fail in a terminal?

Local shell settings can affect STM32CubeMX2 startup and process output. An EPIPE: broken pipe JavaScript popup is a known symptom in this environment. Check the terminal environment before assuming that project configuration is invalid. The popup alone does not establish its cause.

If the first STM32CubeMX2 command reports Cannot find any backend port. in a VS Code terminal, check whether ELECTRON_RUN_AS_NODE is set. This variable can make the Electron-based application run as Node.js instead of starting its backend. Other startup failures can produce the same error, so inspect the command result and logs.

If the variable is set, remove it for the STM32CubeMX2 process and retry the failed command once. In bash or zsh, prefix that command with env -u ELECTRON_RUN_AS_NODE. In PowerShell, remove the variable from the current terminal with Remove-Item Env:ELECTRON_RUN_AS_NODE before retrying. Check whether the failed command changed project state before repeating an operation. If the retry fails, preserve the error and investigate backend startup.

Why did setup stop on an existing deployment?

setup is for a project that has not already been deployed by the installer. Use project-add or project-remove to change contexts in a deployed project, then run doctor --fix. The installer user manual describes the project update procedure.