Troubleshooting

Common Issues

Build Fails: “West not found”

Solution 1: Ensure Python virtual environment is set up:

onsemi: West: Setup Python Environment

Solution 2: To set path to West manually, add the path to virtual environment containing West:

1. Go to File → Preferences → Settings (or press Ctrl+,)

2. Search for: onsemi.venv.path

3. Set the value to the absolute path of your Python virtual environment folder (e.g., C:/workspace/zephyr/.venv)

4. Close the settings

Fig. 19 Setting the virtual environment path in VS Code settings

IntelliSense Not Working

Solution 1: Refresh IntelliSense configuration:

onsemi: IntelliSense: Refresh configuration

Solution 2: Try switching provider:

onsemi: IntelliSense: Switch Provider

Debugging Fails: “No Active ELF File”

Solution: Ensure your project is built and ELF file is detected:

1. Build your project: onsemi: Project: Build

2. Check status bar for active ELF indicator

3. If not shown, manually select: onsemi: Project: Select Active ELF

4. Or rescan: onsemi: Project: Rescan ELFs

Debug Configuration Not Found

Solution: Create a debug configuration using the Debug Configuration panel or manually create a launch.json file in the .vscode folder with a valid configuration.

Board Not Found

Solution: Update West workspace to fetch latest board definitions:

onsemi: West: Update Workspace

Toolchain Not Detected

Solution: Configure using the Configure Settings Panel UI (onsemi Studio Activity Bar → Configuration → Configuration Settings) or manually edit .vscode/settings.json:

{
  "onsemi.toolchain": "C:/path/to/toolchain"
}

Output Shows Certificate Errors

Solution: Configure custom certificate path:

{
  "onsemi.certificatePath": "C:/certs/corporate-ca.crt"
}

Or (not recommended):

{
  "onsemi.allowInsecureTls": true
}

Tip

On Windows, onsemi.git.useWindowsSchannel is enabled by default and makes Git and West validate certificates against the Windows certificate store, which often resolves corporate proxy / custom-CA failures without a certificate bundle. Leave it enabled unless you specifically need the OpenSSL backend.

Toolchain Download Requires Authorized onsemi Access

Symptom: A toolchain (for example, a custom toolchain) is listed as skipped on the setup wizard’s Finish step with a note that it requires authorized onsemi access.

Solution: The tool declares "auth": "github" in tools.json and could not be downloaded because sign-in was cancelled or your account lacks access. Other tools continue installing normally. Once you have authorized onsemi access, re-run the Workspace and Tools Setup wizard to install the skipped toolchains.

Toolchain Extraction Fails with EPERM

Symptom: Installing a toolchain fails with EPERM: operation not permitted, rename ….

Solution: This is usually caused by antivirus / search-indexer scanning or a leftover destination from a previous attempt transiently locking a file. The extractor now clears any pre-existing destination, retries transient locks, and falls back to copy + delete for cross-volume moves. If it still fails, temporarily exclude the install directory from antivirus scanning and retry the install.

J-Link GDB Server Not Found

Solution:

1. Verify J-Link software is installed

2. Add J-Link installation directory to system PATH

3. Or manually specify the path in Debug Configuration → Target Tab

J-Link Version Warning

Symptom: A non-blocking banner in the Debug Configuration panel (or a notification when running west flash) states that J-Link is missing or older than the version recommended by the active SDK.

Solution: The active SDK declares a recommended minimum via minJLinkVersion in its sdk.json. Install or update J-Link from the SEGGER download page (the warning provides a shortcut). Debugging and flashing are never blocked, so you can proceed with the installed version if necessary. onsemi Studio auto-selects the highest installed J-Link version.

Long Path Errors on Windows

Solution:

• Enable “Copy Sample” option when importing applications

• This copies the sample to a shorter path

• Or enable long path support in Windows 10/11

West Commands Fail After Renaming Workspace

Solution:

If you manually rename the directory containing the .venv folder, West commands will fail because the virtual environment contains hard-coded paths.

To fix this:

1. Press Ctrl+Shift+P to open the Command Palette

2. Run: onsemi: West: Set Repository Path and select your renamed workspace

3. Run: onsemi: West: Setup Python Environment to recreate the .venv folder

4. Run: onsemi: West: Install Python Packages to install dependencies

Warning

Avoid renaming directories manually after setting up the workspace. If you must move or rename the workspace, use the commands above to recreate the virtual environment.