1. Yubico
  2. Troubleshooting
  3. General

Initial YubiKey troubleshooting

Avatar
Laura
Created - Updated 

manual-icon.svg Note: If you're attempting to troubleshoot a Security Key, refer to this article.

This article brings up some initial troubleshooting steps to help identify what might be wrong with your YubiKey. Please know that this may not solve your issue, but it’s worth trying the steps out below before submitting a ticket with our support team for further troubleshooting. 

Before starting the troubleshooting, please make sure to remove any initial USB hubs, extensions, etc., Insert the key directly into your device.

 

  1. Is the YubiKey physically powered on?
    Plug in the key and check whether the LED turns on. If it doesn't, try flipping the key over and inserting again; some USB ports are upside down. See here for a visual example of how the YubiKey 5 Nano looks when properly inserted into a USB port.
  2. Is the YubiKey seen by your Operating System?
    Please check that YubiKey OTP+FIDO+CCID or similar appears in one of the following locations when the key is inserted. The YubiKey Bio will appear here as YubiKey FIDO, and our Security Keys will show as "Security Key by Yubico".
    • Windows users check Settings > Devices > Bluetooth & other devices.
    • macOS users check (Apple Menu) > About This Mac > System Report > Hardware > USB.
    • Linux users check lsusb -v in Terminal.
  3. Is the YubiKey’s touch sensor working?
    Test WebAuthn by following the steps here. Successfully completing the WebAuthn demo confirms that the YubiKey's touch sensor is working properly.
    • YubiKeys use capacitive touch sensors, so if your skin is dry, it will be harder for a touch to be recognized. Lotion may help this, and you can also try applying more pressure to make sure your finger covers more of the sensor.
    • The touch sensor is the golden part of your YubiKey (or the round black circle of the YubiKey Bio).

  4. Have any interfaces been disabled on the YubiKey?
    Instructions on re-enabling the interfaces can be found in the following article: Enabling or Disabling USB Interfaces.
  5. Is Yubico OTP working? (YubiKey 5 series only)
    Test your Yubico OTP by following the steps here.
    • In case Yubico OTP is not working, you can find instructions on how to reset the application here.

  6. Have you registered a fingerprint? (YubiKey Bio series only)
    For the YubiKey Bio series, make sure you have enrolled at least one fingerprint - see this page for initial setup instructions.
    • Additional troubleshooting steps for the YubiKey Bio can also be found on this page under Frequently asked questions (near the bottom).
       
      manual-icon.svg Note:
      The YubiKey Bio Multi-protocol Edition supports using fingerprint 
verification
      in lieu of the PIN when performing cryptographic operations. 
In the case of PIV smart card however, to provide users with this fingerprint
option, client software or middleware is required. Yubico has implemented
support for this in the Yubico Minidriver from version 4.6.1. If users
attempt to use PIV smart card on the YubiKey Bio Multi-protocol Edition without supporting middleware, they will encounter limitations.

      In scenarios where supporting middleware is not available or not utilized,
users can still access the PIV application on the YubiKey Bio Multi-protocol
Edition. However, they will not have the option to utilize fingerprint
authentication for cryptographic operations. Instead, they will need to rely
on traditional methods such as entering a PIN.

      While users can still access the PIV application and perform cryptographic
operations, they miss out on the convenience and potentially enhanced
security offered by biometric authentication. Without the fingerprint
option, users may need to rely on the PIN.
  7. Have you followed troubleshooting instructions for the service/app that isn’t working properly with the YubiKey?
    You can find security setup instructions for many services in our Works with YubiKey Catalog, or on the service providers web site. 

  8. Is the issue localized?
    Test the YubiKey on another device. Try repeating the steps outlined above and confirm if the YubiKey works. If it works, the issue could be with the device and/or its USB-ports. 

Does the issue still persist? Please open a support ticket. 

If the above steps don't resolve your issue, consider opening a support ticket here for further assistance. When filing a ticket, please include as many of the following items as possible:

  1. What you are trying to accomplish overall, a link to the steps you are following if applicable, and clarification on what is not working.
  2. Test the YubiKey on our demo site and send us the result. 
  3. Screenshots of the Home and Toggle applications tabs from Yubico Authenticator (Desktop version).
    • Note in Windows 10 and 11, you will need to run Yubico Authenticator with Administrator privileges in order to access the FIDO2/Passkeys settings.
  4. Which operating system and browser you are using, including versions.
  5. The order number or invoice from your YubiKey purchase.
  6. If able to test on multiple machines, whether the problem occurs on both.