LaserCanvas
GRBL alarm and error codes explained
An alarm means GRBL no longer trusts the machine position and has stopped everything — clear it with $X (unlock) or, better, $H (re-home). An error means GRBL rejected one line of G-code and carried on; the job is usually already ruined but the machine is fine. ALARM:1 is a hard limit hit, ALARM:2 is a job larger than the machine, and ALARM:9 is a homing switch that was never found.
Alarms and errors are not the same thing
This distinction causes more confusion than the codes themselves, and it is worth getting straight before looking anything up.
| Alarm | Error | |
|---|---|---|
| What it means | GRBL has entered a locked state and does not trust its position | GRBL rejected one line and moved on |
| Motion | Everything stops. No further motion is accepted | Continues with the next line |
| Clearing it | $X to unlock, or $H to home | Nothing to clear — fix the file |
| Your job | Stopped where it stopped | Usually already wrong, because a line was skipped |
The alarm codes
GRBL 1.1 defines nine. Four of them are about homing and two are about probing, which on a laser you will mostly meet through a Z-touch accessory.
| Code | GRBL means | On a laser, this usually is |
|---|---|---|
| ALARM:1 | Hard limit triggered. Position is lost | The head physically reached a limit switch. Either the job was placed off the bed, or the switch is noisy. Re-home. |
| ALARM:2 | G-code motion target exceeds machine travel | The job is bigger than the machine, or the work origin is set so the job runs off the edge. Position is safe — $X and reposition. |
| ALARM:3 | Reset while in motion. Position is lost | Something reset the controller mid-job: a soft reset, a USB dropout, or a brownout. Re-home and look at power and cabling. |
| ALARM:4 | Probe fail — probe not in expected initial state | The probe input is already triggered. Usually a wiring short or an inverted probe pin. |
| ALARM:5 | Probe fail — no contact within programmed travel | The probe never touched. Check the clip, the plate and the travel distance. |
| ALARM:6 | Homing fail — reset during homing | Something reset the board mid-home. Same causes as ALARM:3. |
| ALARM:7 | Homing fail — safety door opened during homing | A door interlock opened, or $41/door-pin configuration is wrong on a machine with no door. |
| ALARM:8 | Homing fail — could not clear the limit switch on pull-off | The switch stays triggered after backing off. Increase the pull-off distance ($27), or the switch is stuck or miswired. |
| ALARM:9 | Homing fail — limit switch not found within the search distance | The most common homing failure. The axis moved the wrong way, the switch is dead, or $130–$132 max travel is set too small. |
The error codes you will actually see
GRBL 1.1 defines thirty-eight errors. Most are G-code syntax problems that only appear if you are writing G-code by hand or using a broken post-processor. These are the ones that come up with real laser jobs.
| Code | GRBL means | What to do |
|---|---|---|
| error:1 | A G-code word had a letter but no value | Malformed file. Regenerate it rather than patching it. |
| error:2 | Bad numeric value | Often a locale problem — a comma used as a decimal separator. |
| error:3 | Unrecognised $ system command | You sent a setting this firmware does not have. Check the firmware version with $I. |
| error:5 | Homing is not enabled in settings | $22=1 to enable homing, once you actually have switches. |
| error:8 | $ command needs GRBL to be idle | Stop the job before changing settings. |
| error:9 | G-code locked out during alarm or jog | You are in an alarm state. Clear it first — that is the real problem. |
| error:10 | Soft limits need homing enabled | Either enable homing ($22=1) or turn soft limits off ($20=0). They only make sense together. |
| error:15 | Jog target exceeds machine travel | Harmless. The jog was refused because it would leave the bed. |
| error:17 | Laser mode requires PWM output | $32=1 was set on a board whose spindle pin cannot do PWM. |
| error:20 | Unsupported or invalid G-code command | Usually a post-processor emitting something GRBL does not implement, such as a canned cycle. |
| error:22 | Feed rate has not been set | A G1 move with no F before it. A file generation bug. |
| error:24 | Two commands both needing XYZ words in one block | Hand-edited G-code, almost always. |
| error:33 | Invalid motion target | An arc that cannot be traced, or a probe target equal to the current position. |
Anything not on this list is almost certainly a file generation problem rather than a machine problem. The relevant question is what produced the G-code, not what your machine settings are.
Is my machine actually GRBL?
Send $I. GRBL answers with its version and build. Three families share this command set and mostly share these codes:
- GRBL 1.1 — the reference implementation. The codes above are its own.
- FluidNC — GRBL-compatible and reports the same alarm numbers, but it is configured with a YAML file rather than
$numbers, so$130style advice does not transfer. - GRBL-Mega, grblHAL and vendor forks — largely the same codes, sometimes with extras above 38.
Marlin and Smoothieware are different firmware with different messages entirely. If your machine answers $I with something that is not a GRBL version string, none of the numbers on this page apply.
Reading the status line
Sending ? at any time returns a one-line status report, and it answers most alarm questions faster than any lookup table.
- The first field is the state:
Idle,Run,Hold,Jog,Alarm,Door,Check,HomeorSleep. MPos:is machine position,WPos:is work position. A machine that has never homed reports these relative to wherever it powered on.Pn:lists triggered pins —X,Y,Z,P(probe),D(door). IfPn:Xappears with nothing touching the switch, you have found your ALARM:9.Bf:is the buffer state, which matters when diagnosing stutter rather than alarms.
A checklist for a machine that alarms on every home
- Send
?and readPn:. If a limit letter is already listed, the switch is stuck, miswired or inverted ($5). - Press each switch by hand and re-send
?. The letter should appear only while pressed. - Check
$23— the homing direction mask. An axis homing away from its switch gives ALARM:9 every time. - Check
$27— the pull-off distance. Too small and you get ALARM:8. - Check
$130,$131,$132— max travel. Homing searches 1.5× this distance; set it too small and the switch is never reached. - Only after that, consider noise. Unshielded limit wiring running alongside stepper cables causes intermittent ALARM:1 mid-job, and it will look random.
Common questions
What is the difference between $X and $H?
$X unlocks the alarm state without changing what GRBL believes about position. $H runs a homing cycle and re-establishes position against the switches. After ALARM:1 or ALARM:3 the position is genuinely unknown, so $H is the correct response; $X is for jogging off a switch before homing.
Why do I get ALARM:2 when my design clearly fits on the bed?
Because ALARM:2 is about machine travel from the current origin, not about the bed. If the work origin is set near one edge, a job that fits the bed can still run off the end of the travel. Re-home, set the origin, and check the job bounds from there.
My machine alarms randomly in the middle of long jobs. Which code is that?
Usually ALARM:1 or ALARM:3. Both are consistent with electrical noise rather than a real fault: unshielded limit switch wiring, a bad USB cable, or a supply that sags when the laser fires. Try a different USB cable and route limit wiring away from stepper and laser cables before changing any settings.
Do these codes apply to FluidNC?
The alarm numbers do — FluidNC reports the same set. The remedies that reference $ settings often do not, because FluidNC is configured through a YAML file. Look up the equivalent key in your config rather than sending $130=.
Can I just disable alarms so they stop interrupting?
You can turn off hard limits ($21=0) and soft limits ($20=0), and people do. It removes the message, not the condition — the head still hits the end of its travel, it just does so without stopping. On a machine with a laser in it, that is the wrong trade.