GRBL alarms and errors, explained
The controller halts and reports an alarm or error code, and the sender refuses to run until it is cleared. GRBL raises these deliberately: an alarm means it can no longer trust its position or a limit was hit, so it stops rather than crash the machine. The codes are terse, but each maps to a specific, fixable cause. Codes and behaviour are per the GRBL documentation.
Quick answer. An alarm means GRBL has lost confidence in its position or hit a limit and has locked the machine to protect it. The general recovery is to clear the alarm ($X to unlock), re-home so position is known again, and then fix the underlying cause - a triggered limit switch, a homing failure, or a job that exceeds the work area.
Work down the list, most likely first
These are ordered by how often they are the answer, not by severity. Check each in turn and stop at the first one that confirms.
- 1
Alarm 1 - hard limit triggered
Confirm it's this
A limit switch was hit during motion. Position is now unknown because the machine was stopped abruptly, so GRBL will not trust its coordinates.The fix
Clear with $X, jog off the switch, and re-home to re-establish position. Then address why it hit the limit: work origin set too close to the edge, a job larger than the envelope, or a switch triggering falsely from noise or a loose mount. - 2
Alarm 8 and 9 - homing fail (limit switch not found)
Confirm it's this
Homing runs but never sees the switch, or does not reach it within the expected distance, and times out. Nothing is confirming the machine reached its reference.The fix
Check the limit-switch wiring and that the switch actually triggers (watch the status), confirm the homing direction is correct, and set an adequate pull-off distance. A frequent trap: powering the board from USB alone cannot drive the steppers far enough off the switch - use the proper motor supply. - 3
error: machine locked (Alarm state active)
Confirm it's this
Any move is refused and the machine reports it is locked. GRBL blocks motion after an alarm or a reset until you explicitly acknowledge it.The fix
Send $X to unlock. If homing is enabled, the correct next step is to home ($H) rather than just unlocking, so position is genuinely known and soft limits mean something. - 4
Homing not configured (or not enabled)
Confirm it's this
The machine has limit switches but will not home, or complains homing is required. The homing cycle is switched off in settings, or the switches are not set up.The fix
Enable homing ($22=1) once your limit switches are wired and confirmed, set the homing direction mask and pull-off, and test with the axes clear. Do not enable soft limits until homing works, because soft limits depend on a known machine position. - 5
Soft-limit error
Confirm it's this
The controller stops a job because a commanded move would exceed the configured work area - typically the workpiece origin is set wrong or the job is larger than the machine.The fix
Re-check your work-coordinate zero and confirm the job fits inside the travel from that origin. Soft limits are doing their job - they caught a move that would have crashed into a hard stop.
Stopping it coming back
- Home the machine at the start of every session so position is always known.
- Set work zero with margin from the edges, and confirm the job fits the envelope before running.
- Wire limit switches cleanly and power the controller from its proper supply, not USB alone.
- Only enable soft limits after homing is working reliably.
Frequently asked
- What does '$X' do in GRBL?
- $X clears an alarm and unlocks the machine so it will accept motion again. It does not fix the cause - if homing is enabled, follow $X with a homing cycle ($H) so GRBL actually knows where the machine is, otherwise soft limits and coordinates are meaningless.
- Why does GRBL Alarm 1 keep happening?
- Alarm 1 is a hard-limit hit. Recurring ones usually mean the work origin is too close to an edge, the job is bigger than the work area, or a limit switch is triggering falsely from electrical noise or a loose mount. Re-home, give the job margin, and check the switch wiring and shielding.
- My homing fails and the switch never triggers - why?
- Check three things in order: that the switch physically triggers and is wired to the right pin (watch the status report while you press it), that the homing direction is correct so the axis moves toward the switch, and that the controller has real motor power - USB-only power often cannot drive the steppers far enough to reach and pull off the switch.
Keep going
Diagnostic patterns are distilled from manufacturer documentation and established tooling references; where the community converges on a real-world tell, we state it. Exact feeds and speeds always come from the calculator, never invented here.