PCB Troubleshooting Guide

This guide will attempt to diagnose common PCB issues by looking at common symptoms, as well as any possible fixes to get your PCB working properly again. As always, it is recommended to test your PCB before assembling your keyboard. This will save time if any issues are discovered later on and isolate any issues to manufacturer defects or shipping damage rather than user damage.

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 Remap website, click on the ... dropdown menu, enable Test Matrix mode, then test each key on your PCB.
Alternatively, visit the VIA website, install the VIA application, open the application, navigate to the Key Tester tab, enable Test Matrix, then test each key on your PCB.

Windows: "USB device not recognized"

When connecting your PCB to your computer, Windows will detect that a device has been connected but can't recognize it. This means the PCB isn't dead and it may be possible to resolve the issue. Common causes include:

A malfunctioning USB hub.
A malfunctioning USB cable.
A malfunctioning adapter from USB-C or mini-USB to USB-A.
Solder flux causing a short. For solder PCBs, try cleaning up the solder flux and reflowing each solder joint.
Unplug the JST cable and check the JST connector on the daughterboard and PCB for bent pins. Straighten using tweezers if necessary.

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.
If "tape mod" was applied to the PCB, remove the tape.
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 Unified Daughterboard repo 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 the issue is isolated to the electronics for the non-functioning key. A 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.
Jump the hotswap socket by touching the two silver-colored metal pads on the left and right using metal tweezers or other electrically-conductive tools. If a key input is detected, either the switch is defective or the hotswap socket leaves are not making contact with the metal switch pin.
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.
Try flashing the firmware for your PCB again using QMK Toolbox.

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.
If "tape mod" was applied to the PCB, remove the tape.
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.

A key is detected as being held down when it isn't

When your key tester is showing a key as being held down when it isn't, it is usually caused by a short underneath the PCB, but can also be inconsistent and happen at random. The first step is to open up your case, take the PCB out, then check if the issue persists. If it goes away, something electrically conductive underneath the PCB is shorting the switch pins or hotswap sockets. Make sure the plate/PCB is mounted properly and remove anything underneath the PCB such as tape-mod or case foam to isolate the cause.

If your keyboard uses a USB daughterboard, check if the screws are shorting the switches. If they are, try only installing the rear screws or using screws with thinner heads such as button head or wafer head.
"Tape-mod" can sometimes cause some switches to short and send inputs to your computer. If you are using this mod and the issue persists after taking the PCB out of the case, this may be a cause.
Reboot your computer. Some users have reported a reboot fixing this issue.

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 Discord server for help from community members, or to contribute to this troubleshooting guide.