Troubleshooting XSCT issues

This page provides instructions for troubleshooting issues with the Xilinx XSCT tool and VisualGDB.

XSCT is a part of the Xilinx Vitis environment that allows creating, building and configuring projects programmatically. VisualGDB launches XSCT in the background each time you create, debug or change a Vitis-based project.

However, under some circumstances, XSCT might fail to start properly. The first step to troubleshoot such issues would be to check the <Project Directory>\.visualgdb\XSCT-Wizard.log file, if using wizard. If the project has already been created, you can enable XSCT logging via VisualGDB Project Properties and then check the <Project Directory>\XSCT.log file:

If the log file doesn’t help, please follow the steps below to troubleshoot the issue further:

  1. Enable the XSCT Diagnostics Mode under Tools->Options->VisualGDB->Xilinx:
  2. Try creating a new project, or otherwise reproducing the XSCT failure. Once the diagnostic mode is enabled, instead of launching XSCT in the background, VisualGDB will launch it in a separate command prompt window and ask you to enter the “xsdbserver start” command:
  3. Run the command shown by VisualGDB (it will be copied to the clipboard) and press OK after you see the “done-<GUID>” line:
  4. VisualGDB will now connect to XSCT and query various information from it:
  5. If the XSCT prompt (xsct%) does not appear, the XSCT process might be exiting immediately after being launched. If this is the case, try running it again from the command prompt window started by VisualGDB. The typical command is <Vitis directory>\bin\xsct.bat -n -interactive:
  6. If XSCT exits again, try running it from another command prompt window. If it works differently, try running the “set” command from both command prompt windows and comparing the output. You can then try adjusting the variables in the window launched by VisualGDB by running the “set” command, e.g. “set PATH=C:\WINDOWS\system32;C:\WINDOWS;C:\EXTRAS” and then running xsct.bat again.
  7. If changing the PATH variable fixes XSCT issues, you can configure VisualGDB to set it to a custom value via Tools->Options->VisualGDB->Xilinx->XSCT Path Override:If the issue is caused by another variable, you can hardcode it inside xsct.bat.
    Note that normally VisualGDB resets XSCT PATH to “%WINDIR%\system32;%WINDIR%” to avoid conflicts with other tools. However, in some cases, this still doesn’t work, and the correct PATH needs to be found experimentally.