Build Troubleshooter
Pick the symptom you are seeing and get ranked probable causes with the specific check and fix for each, ordered from cheapest to most invasive.
Tool Operation Area
Ranked causes — work from the top
Switch not fully seated in the hot-swap socket
CheckPull the switch and inspect both metal pins for bends, then re-seat with the PCB supported from below.
FixStraighten pins with tweezers and press the switch in until it clicks flush with the plate.
Worn or contaminated contact leaf
CheckSwap the switch into a known-good position. If the chatter follows the switch, the switch is at fault.
FixReplace the switch, or open it and clean the leaf with isopropyl alcohol.
Firmware debounce too low
CheckChatter appears on multiple unrelated keys.
FixRaise the debounce value in firmware to 8-10 ms and reflash.
Damaged socket or lifted pad
CheckChatter stays with the position after swapping switches.
FixReflow or replace the socket, adding a slightly larger solder fillet.
Never desolder anything until the swap test has confirmed the fault stays with the position rather than following the switch.
Working Principle
Most build faults have a small number of causes, and the efficient way to fix them is to test in order of likelihood and cost. Key chatter, where one press registers twice, is usually a contact issue: a dirty or worn leaf, a partially seated switch in a hot-swap socket, or debounce set too low in firmware. The cheapest check is re-seating the switch, then swapping it to a known-good position to see whether the fault follows the switch or stays with the socket — that single test separates a switch fault from a PCB fault. A dead key follows the same logic: swap the switch, and if the position is still dead the problem is the socket, a broken trace or a cold solder joint. Sticking keys are almost always mechanical interference rather than electrical: a keycap fouling the switch housing, foam pushing the PCB out of plane, or a stabilizer binding. Stabilizer noise splits into rattle, tick and bind as described in the stabilizer tool. Crooked switches come from bent pins, from 3-pin switches in a thin plate, or from a plate that is not fully seated. Firmware faults look mechanical but are not: a key that outputs the wrong character or a layer that will not activate is a keymap problem, which is why the troubleshooter always asks you to confirm behaviour in a key tester before disassembling anything.
How to Use
- 01Select the symptom that most closely matches what you observe.
- 02Work through the ranked causes from the top; each lists the check to perform before the fix.
- 03Use the swap test whenever the fault is confined to one key — it is the single most informative diagnostic.
- 04If the fault survives every mechanical fix, reflash firmware before assuming hardware failure.
- 05Beginner warning: do not desolder anything until the swap test has confirmed the fault is on the PCB side.
FAQ
My key registers twice. Is the switch dead?
Not necessarily. Re-seat it first, then swap it to another position. If the double press follows the switch, replace the switch; if it stays, the socket or firmware debounce is at fault.
How do I know if it is firmware or hardware?
Test in an online key tester. If the wrong keycode appears rather than nothing at all, it is a keymap issue.
A key stopped working after I added foam. Why?
Foam cut too large pushes the PCB away from the plate, partially unseating switches. Trim it with clearance on every side.
Is a rattling spacebar normal?
It is common but fixable. It is a stabilizer tuning problem, not a defect; work through the stabilizer plan.
Related Tools
Stabilizer Tuning Calculator
Get a lube, shim and wire-bend plan for your stabilizer set.
Switch Compatibility Checker
Verify switch, socket and plate cutout compatibility before you order.
Hot-swap Socket Selector
Pick the right socket type for your PCB thickness and switch pins.
Keyboard Glossary
Searchable plain-English definitions for custom keyboard terminology.