Introduction to YubiKey Troubleshooting
YubiKeys are powerful security devices that can enhance your authentication and encryption practices. However, like any technology, you may encounter issues while setting up or using your YubiKey. This troubleshooting guide will help you diagnose and resolve common YubiKey problems.
Troubleshooting Hub Navigation
This page serves as your starting point for resolving YubiKey issues. From here, you can navigate to specialized troubleshooting modules based on your specific problem:
Connectivity Issues
Resolve problems with USB connections, device detection, and driver conflicts
Application Integration
Fix issues with browser integration, email clients, and third-party applications
Authentication Problems
Troubleshoot FIDO/WebAuthn, OpenPGP, and SSH authentication errors
Hardware Diagnostics
Test YubiKey functionality, identify hardware failures, and get warranty support
General Troubleshooting Methodology
Before diving into specific issues, it's important to understand a systematic approach to troubleshooting YubiKey problems. Following these steps will help you identify and resolve issues more efficiently:
- Identify the exact problem - Be specific about what isn't working. "YubiKey not working" is too vague; "YubiKey not recognized when plugged into USB port" is more helpful.
- Check the basics first - Ensure the YubiKey is properly inserted, try different USB ports, and verify the YubiKey isn't physically damaged.
- Verify software requirements - Confirm you have all necessary software installed (YubiKey Manager, GPG, etc.) and that they're updated to the latest versions.
- Isolate the issue - Try the YubiKey on a different computer or with a different application to determine if the problem is with the YubiKey itself or with a specific environment.
- Check for recent changes - Consider any recent system updates, software installations, or configuration changes that might have affected your YubiKey functionality.
- Consult logs and error messages - Look for specific error codes or messages that can provide clues about what's wrong.
Quick Solutions for Common Issues
YubiKey Not Recognized
- Try a different USB port
- If using USB-C adapter, try connecting directly if possible
- On Windows, check Device Manager for unknown devices
- On macOS, verify with System Information app under USB
- On Linux, check output of
lsusbcommand
PIN Issues
- If PIN is locked, refer to our Recovery and Reset guide
- For Admin PIN problems, you may need to reset the OpenPGP application
- Remember PINs are separate from your computer user password
- Default PIN is typically "123456" and default Admin PIN is "12345678"
Touch Not Registering
- Ensure you're touching the correct area (metal contact)
- The touch may need to be held longer depending on the operation
- For YubiKey Bio, clean the sensor with a lint-free cloth
- Verify touch policies are correctly set in YubiKey Manager
Software Compatibility
- Verify you're using the latest versions of YubiKey software
- Browser-based operations work best with Chrome, Firefox, or Edge
- For OpenPGP usage, verify GnuPG version 2.1.1+ (GPG4Win on Windows)
- Check Yubico's compatibility list for your YubiKey model
Before Contacting Support
- Document the exact steps that lead to your issue
- Note your YubiKey model and serial number (found on the back of the device)
- Record your operating system and software versions
- Try the troubleshooting steps in the relevant specialized module
- Search Yubico Support forums for similar issues
Using YubiKey Manager for Diagnostics
YubiKey Manager (YKM) is a powerful tool for diagnosing issues with your YubiKey. It provides information about your device status and can help with configuration problems.
Basic Diagnostic Steps with YubiKey Manager
- Install YubiKey Manager - Download from Yubico's website if not already installed
- Launch the application - YubiKey Manager should automatically detect your YubiKey when inserted
- Check device information - The application will display model, firmware version, and enabled applications
- Verify application status - Check which applications (FIDO2, OpenPGP, etc.) are enabled on your YubiKey
- Test functionality - Use the application-specific tools to test features like OTP, FIDO, or PIV
# Install ykman (YubiKey Manager CLI)
# On macOS
brew install ykman
# On Ubuntu/Debian
sudo apt install yubikey-manager
# Basic device information
ykman info
# List configured OpenPGP keys
ykman openpgp info
# Check FIDO applications
ykman fido info
# Verify OTP slots
ykman otp info
When to Reset Your YubiKey
Resetting your YubiKey should be considered a last resort as it will erase all configuration and keys stored on the device. However, in some cases, it may be necessary:
- When you've completely locked yourself out with incorrect PINs
- If you suspect the device has been compromised
- When you want to repurpose the YubiKey for a different use case
- If you're experiencing persistent, unexplained functionality issues
Before resetting, ensure you have backups of any important keys and understand that all data on the YubiKey will be permanently erased. For step-by-step reset instructions, visit our YubiKey Recovery and Reset guide.
Specialized Troubleshooting Modules
We've developed detailed troubleshooting guides for specific problem categories. Explore these specialized modules:
Connectivity Troubleshooting
In-depth diagnostics for USB connection problems, device detection issues, and driver conflicts across different operating systems.
View guideApplication Integration Guide
Solving integration issues with browsers, email clients, password managers, and other applications that use YubiKey functionality.
View guideAuthentication Problem Solver
Resolving issues with FIDO/WebAuthn protocols, OpenPGP key usage, and SSH authentication using your YubiKey.
View guideHardware Diagnostic Toolkit
Complete guide to testing YubiKey functionality, identifying hardware failures, and navigating the warranty/replacement process.
View guide