Alveo Card Debug Guide

Quickly isolate, debug, and resolve a wide range of Alveo™ card related issues within the Vitis™/XRT flow, from card install through to hardware validation.

Debug support using XRT 2020.2 release and earlier can be found in this previous release of this guide.


Similar issues are grouped into categories in the table below allowing you to quickly narrow down the problem area. Click on the link matching your issue to be taken to the category. Within each category, an extensive list of encountered issues along with detailed error messages, symptoms and resolution steps are provided.

Supported Cards

  • U55C

  • U50

  • U50LV

  • U200

  • U250

  • U280

Issue Areas

Issue Area

Topics Covered

Card Installation

Recommended process for card installation

  • Available user guides

  • Common issues

Card Validation

Common issues encountered while running xbutil validate

Modifying XRT or Platform

Recommended XRT and platform installation procedures

  • Upgrading XRT or a platform

  • Downgrading XRT or a platform

  • Uninstalling XRT

Card Not Recognized

Common issues with BIOS, OS and lspci card recognition

  • System does not recognize card

  • BIOS settings

  • Usage of USB cable

  • LED status

Package Manager

Package manager install issues

  • yum/apt

  • rpms/debs

  • Package manager install dependencies

XRT Troubleshooting

Common XRT issues

  • XRT drivers not recognizing the card

SC Troubleshooting

Common Satellite Controller (SC) issues

  • Bad XMC error

  • SC version mismatches

  • Zero voltage or temperature

  • SC reporting UNKNOWN or INACTIVE

Application Crash

Steps to determine if hardware is causing an application crash

Power Delivery

Confirmation that hardware (server and card) can work together for heavy acceleration

Common Steps

Reference procedures for all debugging sections

  • Sudo and root access

  • System details including OS release, PCIe™, and CPU status

  • XRT compatibility

  • Determining platform and SC on card and system

  • Monitoring card power and temperature

Xilinx Support

For additional support resources such as Answers, Documentation, Downloads, and Alerts, see the Xilinx Support pages. For additional assistance, post your question on the Xilinx Community Forums – Alveo Accelerator Card.

If you have a suggestion or find an issue, please email


All software including scripts in this distribution are licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

All images and documentation, including all debug and support documentation, are licensed under the Creative Commons (CC) Attribution 4.0 International License (the “CC-BY-4.0 License”); you may not use this file except in compliance with the CC-BY-4.0 License.

You may obtain a copy of the CC-BY-4.0 License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.