YubiKey Hardware Diagnostics

Diagnosing Hardware Issues

When software troubleshooting doesn't resolve your YubiKey problems, hardware issues may be the cause. This guide will help you diagnose physical problems with your YubiKey and determine whether repair or replacement is needed.

Important: Before assuming hardware failure, verify that software and connectivity issues have been ruled out. Check our Connectivity Troubleshooting Guide first.

Physical Inspection

The first step in hardware diagnostics is a thorough visual inspection of your YubiKey:

Visual Inspection Checklist

USB connector damage - Check for bent, broken, or corroded pins in the USB connector. Even slight bending can prevent proper connection.
Physical damage to casing - Look for cracks, warping, or separation in the YubiKey's plastic housing. Water damage may cause discoloration.
Touch sensor condition - Examine the gold touch contact for scratches, heavy wear, or contamination that might interfere with touch detection.
NFC antenna damage - For NFC-enabled YubiKeys, check for damage to the internal antenna (may show as cracks in specific patterns).
Foreign material - Check for dirt, debris, or liquid in the USB connector or around the touch sensor that might cause connectivity issues.

Physical Symptoms of Hardware Failure

Common Signs

YubiKey not detected on any computer or device
Intermittent detection/disconnection when touched
Touch sensor never registers or is overly sensitive
LED light never illuminates when plugged in
Physical damage to casing or connectors
Unusual heat during operation

Less Common Signs

Some applications work but others fail
Certain features (like NFC) not working
Random, unexpected OTP outputs
Touch sensor working, but no response from device
Connection works, but device resets frequently
Device recognized as "unknown device" on all systems

Functional Testing

After visual inspection, perform these functional tests to identify which components of your YubiKey may be failing:

Basic Connection Test

Multiple port test - Try your YubiKey in different USB ports on different computers. This helps determine if the issue is specific to one port or system.
LED observation - When inserted, the YubiKey's LED should light up briefly. No LED activity may indicate power delivery issues or internal hardware failure.
Device recognition check - Use system tools to see if the YubiKey is detected at all:
- Windows: Check Device Manager under "Universal Serial Bus controllers"
- macOS: System Information > USB
- Linux: Run lsusb command
Different OS test - If possible, try the YubiKey on a different operating system to rule out driver-specific issues.

YubiKey Manager Diagnostics

YubiKey Manager (YKM) is the most comprehensive tool for testing YubiKey hardware functionality:

Device detection - Open YubiKey Manager and check if your YubiKey is detected. If not detected in YKM but visible in system tools, this suggests a firmware issue.
Firmware version check - If detected, verify the firmware version is displayed correctly. Incorrect or missing firmware information may indicate corruption.
Application status - Check each application (FIDO2, OTP, OpenPGP, PIV) to see which ones are functional. Some hardware failures affect only specific applications.
Touch testing - Try performing operations that require touch (like generating an OTP) to test the touch sensor functionality.
NFC testing - For NFC-capable YubiKeys, use YubiKey Manager to check if the NFC interface is functioning.

CLI Testing Commands

# Install ykman CLI tool if not already installed
# Windows: included with YubiKey Manager
# macOS: brew install ykman
# Linux: sudo apt install yubikey-manager

# Basic device info
ykman info

# Test OTP functionality
ykman otp info

# Test FIDO2 application
ykman fido info

# Test OpenPGP application
ykman openpgp info

# Test PIV application
ykman piv info

# Test all interfaces (USB/NFC)
ykman config usb --list
ykman config nfc --list

YubiKey Self-Test Feature

Some YubiKey models include a self-test feature that can help diagnose hardware issues:

Open a text editor or any field where you can type
Hold the YubiKey button for 2-3 seconds until the LED starts blinking
While the LED is blinking, touch the button again
The YubiKey will output a test string that looks like random characters
A successful test indicates the basic OTP functionality is working

Note: This self-test only verifies basic functionality and is only available on YubiKeys with OTP capabilities in slot 1. It doesn't test all hardware components or applications.

Component-Specific Testing

If your YubiKey is partially functional, these tests can help identify which specific components are failing:

USB Connection Testing

Power test - If the LED lights up when plugged in, the YubiKey is receiving power through the USB connection.
Connectivity test - If detected in device manager but not functioning, the USB data pins may be damaged while power pins are intact.
Connection stability - If the YubiKey disconnects when gently moved or touched, there may be a loose connection in the USB connector.
Direct observation - Carefully examine the USB connector pins for alignment and integrity. Bent or missing pins will cause connection issues.

Touch Sensor Testing

Basic touch test - If your YubiKey is configured for OTP in slot 1, touch the sensor to see if it outputs the expected OTP string.
Capacitive sensitivity - Try touching the sensor with different pressure and finger positions. A properly functioning sensor should detect light touches.
Response time - The YubiKey should respond immediately to touch. Delayed or inconsistent response may indicate sensor degradation.
Visual inspection - The touch sensor (gold contact) should be clean and free from visible damage or corrosion.

NFC Testing

NFC detection - Use a smartphone with NFC capabilities and Yubico Authenticator app to test if the YubiKey is detected via NFC.
Range testing - Try positioning the YubiKey at different distances from the NFC reader. Functioning NFC should work within 1-4 cm.
Interference check - Test NFC away from metal objects, other electronic devices, and thick cases that might interfere with the signal.
Cross-device verification - If possible, test NFC functionality on multiple NFC-capable devices to rule out device-specific issues.

Internal Component Testing

Memory integrity - If certain credentials or configurations aren't being saved, the internal storage may be failing.
Processor function - Failure to perform cryptographic operations while still being detected suggests processor issues.
Firmware integrity - Unexpected behavior across multiple applications often indicates firmware corruption.
Clock function - For OATH-TOTP, incorrect time-based codes may indicate issues with the internal clock functionality.

Common Hardware Failure Scenarios

Based on the test results, you can identify these common hardware failure patterns:

Physical Damage Failures

Bent USB connector - Device intermittently connects/disconnects or isn't detected at all
Water damage - Corrosion on contacts, unexpected behavior, or complete failure
Cracked casing - May expose internal components to damage
Worn touch sensor - Inconsistent touch detection or requires excessive pressure
Impact damage - Internal component disconnection causing partial or complete failure

Electronic Failures

Firmware corruption - Device detected but applications don't function properly
Memory failure - Configuration or credentials not saving or becoming corrupted
Processor failure - Device recognized but cryptographic operations fail
Circuit damage - Partial functionality where some features work but others don't
Power regulation issues - Inconsistent operation or device resets during use

Age-Related Failures

Contact wear - Erratic connections after years of inserting/removing
Touch sensor degradation - Decreased sensitivity over time
Flash memory wear-out - Configuration changes no longer persist after many rewrites
Battery depletion - For YubiKeys with internal batteries (rare), reduced functionality
Plastic degradation - Brittleness or discoloration affecting structural integrity

Manufacturing Defects

Early failure - Problems appearing shortly after purchase
Connectivity inconsistency - Works in some ports but not others despite no visible damage
Touch calibration issues - Extreme sensitivity or insensitivity from the beginning
NFC antenna defects - Poor NFC range or reliability since purchase
Firmware issues - Unexpected behavior present from first use

Repair vs. Replacement Decision Guide

Based on your diagnostic results, use this guide to determine whether repair or replacement is appropriate:

When Repair May Be Possible

Firmware issues - Some firmware problems can be resolved with reinstallation
Dirty contacts - Careful cleaning of USB or touch contacts may restore functionality
Configuration problems - Resetting applications can resolve certain issues
Minor connector damage - Very slight pin misalignment can sometimes be carefully corrected

CAUTION

YubiKeys are designed to be tamper-resistant. Physical repair attempts may render the device permanently unusable and will void any warranty. Proceed with extreme caution and only as a last resort.

When Replacement Is Necessary

Significant physical damage - Broken plastic, severely bent connectors, or water damage
Complete failure - Device not detected on any system or shows no signs of power
Internal component failure - Issues with the secure element, processor, or memory
NFC antenna damage - Non-functional NFC that was previously working
Security compromise - Any suspected tampering or compromise of the secure elements
Warranty-covered issues - Defects within the warranty period should be handled through replacement

Firmware Recovery Options

Some YubiKey issues that appear to be hardware-related may be firmware problems that can be addressed:

Application reset - Individual applications can be reset without affecting others:
- FIDO2: ykman fido reset
- OpenPGP: ykman openpgp reset
- PIV: ykman piv reset
- OATH: ykman oath reset
Factory reset - Some YubiKey models support a complete reset to factory defaults, removing all credentials and configurations.
Firmware update - Newer YubiKey models support firmware updates that may resolve certain issues (YubiKey 5 series with firmware 5.2.3 or later).

Warranty and Replacement Process

If your YubiKey requires replacement, follow these steps:

Warranty Coverage

Standard warranty - YubiKeys typically come with a 1-year limited warranty against manufacturing defects.
Coverage limitations - Physical damage, water damage, and normal wear are usually not covered.
Proof of purchase - You'll need the original purchase receipt or order information.
Serial number - Locate the serial number printed on the YubiKey (typically on the back or side).

Contacting Yubico Support

Gather information - Before contacting support, collect:
- YubiKey model and serial number
- Purchase date and proof of purchase
- Detailed description of the issue and troubleshooting steps taken
- Photos of physical damage (if applicable)
Submit a support ticket - Visit support.yubico.com and create a support ticket.
Follow instructions - Yubico support will provide specific instructions for your situation, which may involve additional diagnostic steps.
Return authorization - If a replacement is approved, you'll receive an RMA (Return Merchandise Authorization) and shipping instructions.

Preparing for YubiKey Replacement

Before sending your YubiKey back or disposing of it, take these security precautions:

Backup alternate authentication methods - Ensure you have backup access to all accounts protected by the YubiKey.
Factory reset if possible - If the YubiKey is still partially functional, reset all applications to remove sensitive data.
Document configurations - Make notes about your YubiKey configuration to set up the replacement quickly.
Deregister from services - If possible, remove the YubiKey from any services where it's registered.
Physical destruction - For non-warranty returns or disposal, consider physically destroying the YubiKey to prevent data recovery.

Back to Troubleshooting Hub