# Troubleshooting

This chapter contains known problems and recommended solutions. For last-minute issues, refer to *MCUXpresso Secure Provisioning Tool Release Notes* available as part of the SEC tool and on the web (document [MCUXSPTRN](https://www.nxp.com/doc/MCUXSPTRN)).

-   The application must be installed into the location where the user has the write access.
-   By default, the Secure Provisioning Tool does not configure all possible security features that are available in the processor. Only the ones required by the selected boot type are configured. Configure the rest in OTP/PFR/IFR Configuration.
-   If the tool is started with the option `-v` \(verbose mode\), it provides additional details \(logs\) that can be used to analyze problems.

## Windows

-   On the Windows platform, make sure that the Windows FIND utility is found first on the PATH \(GNU find utils could break the functionality\).


## Linux

-   On the Linux platform, the USB and/or Serial device files have to be readable and writable by the current user. To solve this issue, see `resources/udev/99-secure-provisioning.rules` installed into `/etc/udev/rules.d/99-secure-provisioning.rules`. There can be a conflicting rule with higher priority on the machine. In this case, update the conflicting rule or make this rule file so they are applied in the expected order.
-   Ubuntu 22 and USB2Serial CP210x. On Ubuntu 22, there is a conflicting package `brltty` that causes generic issues with the CP210x USB to serial converter. Uninstalling the \`brltty\` package fixes the issue. For more details, see [https://bugs.launchpad.net/ubuntu/+source/brltty/+bug/1970408](https://bugs.launchpad.net/ubuntu/+source/brltty/+bug/1970408)
-   The SEC tool works well with the Xorg display server. Wayland, default in Ubuntu, causes various UI glitches, that is why the application shortcut contains the configuration to use the Xorg \(x11\) backend. If the SEC GUI is executed manually under the Wayland display server, make sure it is executed with proper environment variables, for example:

    `UBUNTU_MENUPROXY=0 GDK_BACKEND=x11 /opt/nxp/MCUX_Provi_v8/bin/securep`.

-   The nxpuuu utility used for i.MX 9x might produce lots of escape characters in the Log view. To reduce the number of escape characters, use the following commands:
    ```
    cd /opt/nxp/MCUX_Provi_25.03/bin/tools/spsdk/
    sudo sh -c "nxpuuu -udev >> /etc/udev/rules.d/70-nxpuuu.rules"
    sudo udevadm control --reload
    ```


## macOS

-   i.MX 9x: Due to a known error in libUUU and the underlying libusb library, the write firmware using nxpuuu or uuu fails. Building of the firmware works.
-   Fields with invalid input are marked with a background red color. Fixing the value might not change the background color correctly and the focus must be changed to another field for correct repaint.
-   PEmicro does not support macOS Aarch64 yet.
-   If an env. variable \(such as variable for EdgeLock 2GO\) must be propagated to SEC executed via launcher, it has to be set using the `launchctl` command, for example:

    `launchctl setenv EL2GO_GPG_SIGN_KEY MY_KEY_ID`

    For a permanent env. variable, see the solution described at [https://github.com/ersiner/osx-env-sync](https://github.com/ersiner/osx-env-sync).


## i.MX RT5xx/6xx

-   Repetitive write to QSPI flash might fail in case the board is not reset and the reset pin is not configured in fuses. For more information, see RT5xx/6xx Device workflow/Booting images in section RT5xx/6xx device workflow in <xref href="06_processor_specific_workflow.md">Processor-specific workflows</xref>.
-   If shadow registers are used, it is necessary to HW reset the processor, before a new image or fuses configuration is applied because the shadow registers can be set into an unsecured processor only.


## i.MX RT1024

-  SD card boot device is not supported for the MIMXRT1024-EVK board due to limitation in the flashloader.


## Debug probes

-   Detecting PEmicro probes and detection of probes after PEmicro was detected has these limitations:
    1.  PEmicro must be connected before the first attempt for detection, if not connected it cannot be detected and the SEC tool must be restarted for detection to succeed.
    2.  When PEmicro is detected, it is impossible to detect any other pyOCD probe without restarting the SEC tool. Also, if PEmicro is once detected it will be always listed as an available probe even if it is not connected anymore.
-   Dependency on USB drivers for debug probe drivers is described in ReleaseNotes.txt in "System requirements".

## Debug authentication

If the Open debug port fails, there are usually no error messages \(due to security reasons, the processor returns only a general error code\). To make it working, check the following items:
-   The processor should not be in ISP mode.
-   The processor should be secured.
-   The operation may fail if the debug port is already opened.
-   After a failed connection test by the debug probe, it might be necessary to reset the processor to be able to open the debug port. On the KW45xx and K32E1xx series it is necessary.

## Zephyr projects

Not every Zephyr example project can be used as it is. Additional workflow or changes in the project are required.
For example, for MCX N devices the QSPI examples require a (MCUBoot) bootloader in the Internal Flash by default. The default start address is not usable for a bootable image creation without the bootloader. For details, see Zephyr documentation for the given board. Either the bootloader in the internal flash has to be used or the start address must be changed. For the mentioned MCUX N devices, the start address can be changed in the `build/zephyr/.config` file:
```
CONFIG_FLASH_BASE_ADDRESS=0x90000000
```
has to be changed to
```
CONFIG_FLASH_BASE_ADDRESS=0x90001000
```

## Custom USB HID devices

If you have a device with custom VID&PID, it is possible to select the custom VID&PID in the main menu > Target > Connection. Selected VID&PID is used for the *whole* write operation. Write script does not support a change of VID&PID during its execution. It is recommended to change VID&PID prior the write operation  (e.g. using PFR dialog or OTP dialog in **Advanced mode**), reset the processor and then start the write operation with custom VID&PID.

For manufacturing operation to work with a custom VID&PID the processor data (`bin\data\targets\<processor>\<processor>.json`) must be modified. Add the custom VID&PID (0x1FFF&0x0153) to the list of USB ports. For manufacturing write device HID can change after reset as long as the new value is in the USB ports list. **Note**: For the manufacturing package, the processor data must be changed on the device where the package is executed.
```
"rom_boot_loader": {
        "usb_ports": [
            {
                "usbVid_int": "0x1FC9",
                "usbPid_int": "0x014F"
            },
            {
                "usbVid_int": "0x1FFF",
                "usbPid_int": "0x0153"
            }
        ]
    }
```