GRBL Alarm and Error Codes: What They Mean and How to Fix Them

Last modified: November 19, 2026

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.

For GRBL setup, see our GRBL guide and GRBL settings.

How to Clear a GRBL Alarm

  1. Find the cause using the table below, and fix it first.
  2. If GRBL says [MSG:Reset to continue], reset it: press your sender's reset button or send Ctrl-X.
  3. Home the machine with $H if you use homing. This is the safe way to unlock, because it re-establishes where the machine is.
  4. Or unlock with $X if 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:

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.