PCB Troubleshooting Guide

This guide is a work-in-progress. Contributions to this guide are welcomed.

Menu key not detecting

The menu key is a special function that switches to a different layer and is processed locally on the PCB. Most key testers will not be able to detect it as it does not send any key codes to your computer. To correctly test your PCB:

• Visit the website, click on the ... dropdown menu, enable Test Matrix mode, then test each key on your PCB.
• Alternatively, visit the website, install the VIA application, open the application, navigate to the Key Tester tab, enable Test Matrix, then test each key on your PCB.

PCB not being detected

When your PCB is not being detected by your computer, this could be caused by a variety of factors. We begin troubleshooting with a simple check of the USB cable and USB ports to ensure the issue is not with the computer or USB cable. If the PCB is not defective and the firmware is simply corrupted or the PCB does not have a firmware installed, your computer may not recognize the keyboard — in this situation, putting your PCB into DFU mode (also referred to as reset mode) will allow QMK Toolbox to detect your PCB. Use QMK Toolbox to flash the PCB with its firmware. When these two troubleshooting steps don't work, a hardware issue likely exists on the daughterboard, JST cable, or the PCB and further troubleshooting will be required to determine the cause.

• Connect your PCB to your computer using different USB cables.
• Connect your PCB to different USB ports on your computer.
• Connect your PCB directly into your computer's USB ports if using a USB hub.
• Try flashing the firmware for your PCB again using QMK Toolbox. If QMK Toolbox does not recognize your PCB after entering DFU (reset) mode, either the host USB port, USB cable, USB daughterboard, JST cable, or microcontroller is damaged.
• Unplug the JST cable and check the JST connector on the daughterboard and PCB for bent pins. Straighten using tweezers if necessary.
• Install another USB-C Unified C3 daughterboard and retry.
• Check that your JST cable's wiring is one-to-one. View the for information on proper cable wiring.
• Carefully and gently touch the surface of the microcontroller to check the temperature. If the microcontroller is hot to the touch, a short could exist and your PCB may need replacement.

A single switch is not working

When a single switch is not working, this usually means the PCB is fine and self-repair is relatively simple and easy to do.

• Locate the key on the bottom of the PCB and check to see that the diode is not missing. Scarlet and Velvet PCBs have extra diodes soldered near the microcontroller that can be desoldered and used to replace the missing diode.
• For solder PCBs, check that the switch has been soldered properly.

• Try flashing the firmware for your PCB again using QMK Toolbox.

• Jump the hotswap socket by touching the two metal pads on the left and right using metal tweezers or other conductive tools.
• Try inserting a different switch to check for a defective switch.
• Ensure the gold contact-leaves on the hotswap sockets are not spread apart too far as this could prevent the leaves from making contact with your switch. Carefully take a fine-tip tool such as tweezers and gently push the leaves back together.
• Check if the hotswap socket has lifted off the PCB. If it is lifted off the PCB, check the left and right pads to see if they have also been lifted off the PCB. If a pad has been lifted, the PCB will need to be replaced or repaired.

Entire column of keys not registering

Most keyboard PCBs do not connect each key individually to the microcontroller; instead, a matrix is used and each key belongs to a specific row and column. A key is considered activated when electricity is flowing through its column and row. When an entire row of keys fail to register any key inputs, it is typically caused by physical damage to the PCB traces — the copper lines that connect each key to the one above and below may have been severed, preventing electricity from flowing through the column and causing the PCB to not be able to detect any of the keys in the column.

• Try flashing the firmware for your PCB again using QMK Toolbox.

• Remove the PCB from the case, connect it to your computer, then jump each key in the column by touching the two contact pads using metal tweezers. This will check if the case or switches are the cause.
• Starting with the top key in the column and using metal tweezers, touch each key's left pad to the left pad on the key below and test if the switches work (maintaining contact with the pads using the tweezer as you test the switches). This will check for damaged traces on the PCB. If the keys in the column begin to function, a trace has been damaged in between the two keys you are jumping and the PCB will need to be replaced or repaired.

Entire column of keys activating together

Most keyboard PCBs do not connect each key individually to the microcontroller; instead, a matrix is used and each key belongs to a specific row and column. When an entire row of keys are activated together, it generally means the PCB is shorting against the bottom case. A short means that electricity is flowing between the switch pins unintentionally, causing the PCB to think that a switch is being pressed even when it isn't.

• Remove the PCB from the case and test the switches again. If the issue goes away, the PCB is likely being shorted by the case or daughterboard screws. Either the PCB and plate assembly was assembled improperly, the mounting system was installed improperly, or incompatible daughterboards were used.
• Alexa and Velvet use thinner-than-normal USB daughterboards — using aftermarket daughterboards with standard 1.6 mm thickness could cause the screws to sit higher than intended. When this happens, either replace the daughterboard with a 1.0 mm thick daughterboard, or switch to thinner button-head or wafer-head screws which have 1.3 mm and 1.0 mm thick screw heads respectively.

Entire row of keys not registering

When a row of keys stop working, this suggests a hardware defect either caused by a damaged horizontal-trace or microcontroller. When this happens, the PCB needs to be replaced.

Every key is in the wrong position

Check to ensure that you have flashed the correct firmware. Some PCBs have different firmwares for their solder and hotswap variants which can cause the keymap to appear scrambled, usually with each key appearing one or two positions to the right or left of where it normally belongs.

One or more keys are double-activating

When a switch is pressed once but it inputs multiple times to your computer, it is typically caused by a damaged contact-leaf inside the switch or a loose connection between the electrical switch pins and the hotswap socket.

• Try inserting a different switch to check for a defective switch.
• Ensure the gold contact-leaves on the hotswap sockets are not spread apart too far as this could cause the switch pin to wobble and briefly break contact before touching the hotswap socket again, registering double-activations to your computer. Carefully take a fine-tip tool such as tweezers and gently push the leaves back together to ensure the switch pins are always in contact with the hotswap socket's leaves.
• Try flashing the firmware for your PCB again using QMK Toolbox.

Issue not listed here?

This guide is a work-in-progress and we are constantly adding to this as new troubleshooting methods are found. Feel free to join our server for help from community members, or to contribute to this troubleshooting guide.