When something goes wrong, GRBL reports a number: ALARM:1 through ALARM:10, or error:1 through error:38. This page explains what every code in GRBL 1.1 means, what usually causes it, and how to fix it.
- Alarm codes mean the machine stopped or can't safely move. GRBL locks out G-code until you clear the alarm.
- Error codes mean GRBL rejected one line it was sent, usually a G-code or
$command it couldn't run. The machine keeps going with the next line, which can be just as bad, so don't ignore them. - Messages in square brackets, like
[MSG:'$H'|'$X' to unlock], are status notes.
For GRBL setup, see our GRBL guide and GRBL settings.
How to Clear a GRBL Alarm
- Find the cause using the table below, and fix it first.
- If GRBL says
[MSG:Reset to continue], reset it: press your sender's reset button or send Ctrl-X. - Home the machine with
$Hif you use homing. This is the safe way to unlock, because it re-establishes where the machine is. - Or unlock with
$Xif you don't use homing, or need to move off a limit switch first. GRBL replies[MSG:Caution: Unlocked]as a reminder that it may not know its position. Re-zero your work coordinates before cutting.
GRBL Alarm Codes
| Code | Text in GRBL 1.0 and earlier | Meaning |
|---|---|---|
| ALARM:1 | Hard limit | A limit switch was triggered |
| ALARM:2 | Soft limit | A move would go past the machine's travel |
| ALARM:3 | Abort during cycle | Reset while the machine was moving |
| ALARM:4 | Probe fail | Probe was already triggered (or not triggered) before the probe move started |
| ALARM:5 | Probe fail | Probe didn't touch anything within the programmed distance |
| ALARM:6 | Homing fail | Homing was reset before it finished |
| ALARM:7 | Homing fail | Safety door opened during homing |
| ALARM:8 | Homing fail | Pull-off didn't clear the limit switch |
| ALARM:9 | Homing fail | Couldn't find a limit switch |
| ALARM:10 | Homing fail | Second switch of a dual-motor axis didn't trigger |
ALARM:1 – Hard limit
A limit switch triggered while hard limits are enabled ($21=1). GRBL stopped instantly, so the motors have probably lost steps and the machine's position is unknown. Reset, move the axis off the switch (unlock with $X and jog away if needed), then re-home with $H.
If no switch was actually hit, the cause is almost always electrical noise on the limit wiring, often when the spindle or router turns on. Use shielded cable, keep limit wires away from motor and spindle wires, and see our guide to electrical noise and grounding. Normally-closed switches (with $5=1) are also less sensitive to noise.
ALARM:2 – Soft limit
The program, or a jog, asked for a move beyond the machine's travel ($130 to $132). GRBL caught it before moving, so the machine still knows where it is and it's safe to unlock with $X.
Common causes: the work zero is set in the wrong place so the job doesn't fit in the remaining travel, the job is bigger than the machine, or the max travel settings are wrong. Check the job's size against where you set zero, and that $130 to $132 match your machine.
ALARM:3 – Abort during cycle
GRBL was reset (Ctrl-X, the reset button, or a sender's stop) while the machine was moving. The sudden stop may have lost steps, so re-home before continuing. A feed hold (!) pauses without this problem.
ALARM:4 and ALARM:5 – Probe fail
ALARM:4 means the probe was in the wrong state before the probe move started: for G38.2 and G38.3 it was already triggered, or for G38.4 and G38.5 it wasn't. Check that the probe clip is connected, the probe isn't touching, and the probe pin isn't inverted ($6).
ALARM:5 means the probe didn't make contact within the distance programmed in the G38.2 or G38.4 move. Start the probe closer to the surface, increase the probe distance, or check the probe wiring (touch the plate to the bit with the clip on and check that your sender shows the probe input change).
ALARM:6 – Homing reset
The homing cycle was interrupted by a reset. Run $H again.
ALARM:7 – Safety door opened during homing
The safety door input triggered during homing. Close the door, or check the door switch wiring, and home again.
ALARM:8 – Homing pull-off failed
After finding a switch, GRBL backs off by the pull-off distance ($27), and the switch was still triggered. Increase $27 (try 2 to 3 mm), or check for a switch that's stuck on or wired wrong.
ALARM:9 – Homing fail, switch not found
GRBL moved an axis the full search distance (1.5 × its max travel setting) without finding a switch. Check, in order:
- Is the axis moving toward its switch? If it heads the wrong way, set the axis bit in
$23. - Does the switch work? Trigger it by hand and check that your sender shows the limit input change.
- Is max travel (
$130to$132) big enough? If it's smaller than the real travel, GRBL gives up too soon. - Is the pull-off (
$27) too large?
ALARM:10 – Dual-axis homing fail
Only on machines with two motors on one axis (a compile-time option). The second switch didn't trigger within the allowed distance after the first. Check the second switch and its wiring, and that the gantry isn't badly racked.
GRBL Error Codes
GRBL sends error: plus a number when it rejects a line. The line wasn't executed, but the rest of the program keeps going, so a rejected line in the middle of a job can leave a cut out or put the next moves in the wrong place.
Command and setting errors
| Code | Meaning | Usual fix |
|---|---|---|
| error:1 | Expected command letter: a G-code word is missing its letter | Check the line for a stray number or garbled characters |
| error:2 | Bad number format: a word is missing its value or the number is invalid | Check for missing values like G1 X F500, or a comma used as a decimal point |
| error:3 | $ command not recognized |
Check the command; $ commands are case sensitive |
| error:4 | Negative value where a positive one is expected | Use a positive value |
| error:5 | Homing isn't enabled | Turn on homing with $22=1 before using $H |
| error:6 | Step pulse must be at least 3 microseconds | Set $0 to 3 or more |
| error:7 | EEPROM read failed; settings restored to defaults | Re-enter your settings. If it keeps happening, the board's EEPROM may be failing |
| error:8 | $ command needs GRBL to be idle |
Wait for the job or jog to finish, or stop it first |
| error:9 | G-code locked out during an alarm or jog | Clear the alarm with $H or $X; see clearing alarms |
| error:10 | Soft limits need homing enabled | Enable homing ($22=1) before soft limits ($20=1) |
| error:11 | Line too long (more than 80 characters) | Remove comments or extra digits; check your CAM post processor |
| error:12 | Setting would make the step rate exceed 30 kHz | Lower max rate ($110 to $112) or steps per mm |
| error:13 | Safety door is open | Close the door or check the door switch |
| error:14 | Build info or startup line is too long to store | Shorten the $N startup line or $I build info |
| error:15 | Jog would exceed the machine's travel | Jog a shorter distance; soft limits are on |
| error:16 | Invalid jog command | A jog ($J=) must include = and only allowed G-codes |
| error:17 | Laser mode requires PWM output | The firmware was built without variable spindle; reflash a standard build |
G-code errors
| Code | Meaning | Usual fix |
|---|---|---|
| error:20 | Unsupported or invalid G-code | GRBL doesn't support that code; use a GRBL post processor (see below) |
| error:21 | Two commands from the same modal group on one line | E.g. G0 G1 or G90 G91 on the same line; split them |
| error:22 | Feed rate not set | Add an F word before the first G1, G2 or G3 move |
| error:23 | Command needs an integer value | E.g. G1.5; check for typos |
| error:24 | Two commands on one line both need axis words | Put each motion command on its own line |
| error:25 | The same word appears twice on one line | E.g. G1 X1 X2; check the post processor |
| error:26 | No axis words for a command that needs them | E.g. a bare G0; add the target position |
| error:27 | Invalid line number | N line numbers can't be larger than 10,000,000 |
| error:28 | Command is missing a required value | E.g. G4 without P, G10 without L or P |
| error:29 | G59.1, G59.2 and G59.3 aren't supported | Use G54 to G59 |
| error:30 | G53 only works with G0 and G1 | Put G0 or G1 on the G53 line |
| error:31 | Axis words on a line where nothing uses them | E.g. axis words after G80; check the post processor |
| error:32 | G2/G3 arc has no axis words in the active plane | Check the plane (G17/G18/G19) and the arc's end point |
| error:33 | Invalid motion target | Usually an arc whose end point can't be reached from its center; check arc output and units |
| error:34 | Invalid arc radius | The R value is too small for the distance between the start and end points |
| error:35 | G2/G3 arc has no offset words in the active plane | Add I, J or K for the active plane |
| error:36 | Unused value words on the line | A value the command doesn't use, such as an R or P word on a G1 line; check the post processor |
| error:37 | G43.1 offset isn't on the tool length axis | Use only a Z value with G43.1 |
| error:38 | Tool number too large | T numbers must be 255 or less |
Fixing error:20 and other G-code errors
Most G-code errors mean the program was written for a different control. GRBL only supports a subset of G-code: no canned drilling cycles (G81 to G89), no cutter compensation (G41/G42), no M6 tool changes, no macros or subroutines, and no G59.1 to G59.3. See the full list of G-codes GRBL supports.
The fix is almost always to re-post the program with a GRBL post processor in your CAM software. Before running it, open it in a G-code viewer such as CutViewer or check it with GRBL's own check mode: send $C, stream the program, and GRBL reports any errors without moving the machine. Send $C again to leave check mode.
GRBL Messages
| Message | What it means |
|---|---|
[MSG:'$H'|'$X' to unlock] |
GRBL started in an alarm state, usually because homing is enabled and the machine hasn't been homed yet. Home with $H. |
[MSG:Reset to continue] |
A critical alarm (hard limit or abort). Reset before GRBL accepts any commands. |
[MSG:Caution: Unlocked] |
You unlocked with $X. GRBL may not know where the machine is. |
[MSG:Check Limits] |
A limit switch reads as triggered at startup. Move off the switch, or check for a wiring fault or noise. |
[MSG:Check Door] |
The safety door input reads open. |
[MSG:Enabled] / [MSG:Disabled] |
Check mode ($C) turned on or off. |
[MSG:Pgm End] |
M2 or M30 ended the program and reset the G-code modes. |
[MSG:Restoring defaults] |
A $RST= command restored defaults. |
[MSG:Sleeping] |
Sleep mode ($SLP); reset to wake up. |
GRBL 1.0 and earlier showed alarms and errors as text instead of numbers (ALARM: Hard limit, error: Unsupported command), as listed in the alarm table above. grblHAL and FluidNC keep these numbers and add codes of their own.
Frequently Asked Questions
How do I clear a GRBL alarm?
Fix whatever caused it, then home the machine with $H or unlock it with $X. After a hard limit or a reset during motion, GRBL first needs a soft reset (Ctrl-X or your sender's reset button). Homing is the safer choice because it re-establishes the machine's position.
What does ALARM:9 mean in GRBL?
ALARM:9 means homing failed because GRBL couldn't find a limit switch within its search distance. Check that the axis moves toward its switch ($23), that the switch works, and that the max travel settings ($130 to $132) aren't too small.
What does error:9 mean in GRBL?
error:9 means GRBL rejected a G-code command because it's in an alarm state (or jogging). Clear the alarm with $H or $X and the commands will work again.
What does error:20 mean in GRBL?
error:20 means the line contains a G-code or M-code GRBL doesn't support, such as a canned drilling cycle, cutter compensation, or M6. Re-post the program with a GRBL post processor in your CAM software.
Why do I get ALARM:1 when no limit switch was hit?
Electrical noise on the limit switch wires is the usual cause, especially when the spindle or router starts. Use shielded cable, route limit wires away from motor and spindle wiring, and consider normally-closed switches. You can also turn hard limits off ($21=0) and rely on soft limits.
What's the difference between a GRBL alarm and an error?
An alarm means the machine stopped, or can't safely move, and GRBL locks out G-code until you clear it. An error means GRBL rejected a single line it couldn't run; it keeps going with the next line.
Be the first to know about updates at CNC Cookbook
Join our newsletter to get updates on what's next at CNC Cookbook.