GRBL v1.1 answers every line with ok or error:N (codes 1–17 and 20–38; 18 and 19 are unused), and reports emergencies as ALARM:N (codes 1–10). The ones people hit most are error:20 (unsupported G-code, for example a G81 canned cycle or M6), error:22 (no feed rate set), error:9 (G-code locked during an alarm), ALARM:1 (hard limit, position likely lost), ALARM:2 (soft limit, position kept) and ALARM:9 (homing found no switch). Clear an alarm with $H (home) or $X (unlock). The tables below are copied from the CSV files in the official gnea/grbl repository (firmware 1.1h); the "what to check" column is ours, written from Grbl's own documentation. To check a program's moves before sending it, paste it into the G-code Explainer & Simulator.
GRBL error codes (error:1 to error:38)
| Code | v1.0 message and meaning | What to check |
|---|---|---|
| error:1 | Expected command letter. G-code words consist of a letter and a value. Letter was not found. | Look for a number with no letter in front of it, or a stray character, on the line. |
| error:2 | Bad number format. Missing the expected G-code word value or numeric value format is not valid. | A letter is missing its number, or the number is malformed (for example a bare X, or X1.2.3). |
| error:3 | Invalid statement. Grbl '$' system command was not recognized or supported. | Unknown $ command. Send $ on its own for the list of valid commands. |
| error:4 | Value < 0. Negative value received for an expected positive value. | A value that must be positive was sent as negative. |
| error:5 | Setting disabled. Homing cycle failure. Homing is not enabled via settings. | $H was sent but homing is off. Set $22=1, which needs limit switches on the axes. |
| error:6 | Value < 3 usec. Minimum step pulse time must be greater than 3usec. | The step pulse $0 must be at least 3 µs (the generic default is 10 µs). |
| error:7 | EEPROM read fail. Using defaults. An EEPROM read failed. Auto-restoring affected EEPROM to default values. | Grbl restored defaults after an EEPROM read failure. Check every setting ($$) and work offset ($#) before running a job. |
| error:8 | Not idle. Grbl '$' command cannot be used unless Grbl is IDLE. Ensures smooth operation during a job. | This $ command only runs when Grbl is Idle. Wait for the job to end, or feed-hold and reset. |
| error:9 | G-code lock. G-code commands are locked out during alarm or jog state. | Grbl is in an alarm or jog state. Clear the alarm with $H (home) or $X (unlock), or wait for the jog to finish. |
| error:10 | Homing not enabled. Soft limits cannot be enabled without homing also enabled. | Soft limits ($20=1) need homing enabled first: set $22=1. |
| error:11 | Line overflow. Max characters per line exceeded. Received command line was not executed. | The line is longer than Grbl's 80-character line buffer. Shorten it (fewer decimals, no long comments) or split it. |
| error:12 | Step rate > 30kHz. Grbl '$' setting value cause the step rate to exceed the maximum supported. | The steps/mm ($100–$102) and maximum rate ($110–$112) settings ask for a step rate faster than Grbl can pulse. Lower one of them. |
| error:13 | Check Door. Safety door detected as opened and door state initiated. | The safety-door input is open. Close the door, then resume with ~ (cycle start). |
| error:14 | Line length exceeded. Build info or startup line exceeded EEPROM line length limit. Line not stored. | A startup line ($N) or build-info string ($I) is too long to store. Shorten it. The interface notes list this one as Grbl-Mega only. |
| error:15 | Travel exceeded. Jog target exceeds machine travel. Jog command has been ignored. | The jog target is outside machine travel ($130–$132) with soft limits on, so the jog was ignored (no alarm). |
| error:16 | Invalid jog command. Jog command has no '=' or contains prohibited g-code. | A jog must start with $J= and may only contain axis words, F, G20/G21, G90/G91 and G53. |
| error:17 | Setting disabled. Laser mode requires PWM output. | Laser mode ($32=1) needs the PWM spindle output, which this build does not have. |
| error:20 | Unsupported command. Unsupported or invalid g-code command found in block. | The command is not in Grbl. Grbl has no canned cycles (G81–G89), no cutter compensation (G41/G42), no G43 (only G43.1), no M6 tool change and no A/B/C axes. |
| error:21 | Modal group violation. More than one g-code command from same modal group found in block. | Two codes from the same modal group are on one line, for example G0 and G1, or G90 and G91. |
| error:22 | Undefined feed rate. Feed rate has not yet been set or is undefined. | No feed rate has been set. Add an F word on or before the first G1, G2 or G3. |
| error:23 | Invalid gcode ID:23. G-code command in block requires an integer value. | The code has a decimal that Grbl does not support, for example M3.1. G and M numbers must be whole numbers unless Grbl lists the decimal form (G38.2, G43.1…). |
| error:24 | Invalid gcode ID:24. More than one g-code command that requires axis words found in block. | Two commands on one line both use X/Y/Z axis words (for example G28 and G1). Put them on separate lines. |
| error:25 | Invalid gcode ID:25. Repeated g-code word found in block. | The same word appears twice on the line, for example two X words. |
| error:26 | Invalid gcode ID:26. No axis words found in block for g-code command or current modal state which requires them. | A command that needs axis words has none, for example a G1 with no X, Y or Z. |
| error:27 | Invalid gcode ID:27. Line number value is invalid. | The N line number is outside 1 to 9,999,999. |
| error:28 | Invalid gcode ID:28. G-code command is missing a required value word. | A required P or L word is missing (for example G10 needs L2 or L20 and a P number). |
| error:29 | Invalid gcode ID:29. G59.x work coordinate systems are not supported. | G59.1, G59.2 and G59.3 are not supported. Use G54 to G59. |
| error:30 | Invalid gcode ID:30. G53 only allowed with G0 and G1 motion modes. | G53 only works with G0 or G1 active. |
| error:31 | Invalid gcode ID:31. Axis words found in block when no command or current modal state uses them. | Axis words were sent with no motion mode to use them (G80 is active). Add G0 or G1. |
| error:32 | Invalid gcode ID:32. G2 and G3 arcs require at least one in-plane axis word. | A G2/G3 arc has no end-point word in the active plane (X or Y for G17). |
| error:33 | Invalid gcode ID:33. Motion command target is invalid. | The target is impossible: an arc that cannot be drawn, or a G38.2 probe target equal to the current position. |
| error:34 | Invalid gcode ID:34. Arc radius value is invalid. | The R-format arc could not be computed. Split it into semicircles or quadrants, or use I/J/K centre offsets. |
| error:35 | Invalid gcode ID:35. G2 and G3 arcs require at least one in-plane offset word. | An I/J/K-format arc is missing the offset word for the active plane. |
| error:36 | Invalid gcode ID:36. Unused value words found in block. | The line has words that no command uses. Remove them. |
| error:37 | Invalid gcode ID:37. G43.1 dynamic tool length offset is not assigned to configured tool length axis. | G43.1 can only offset its configured tool-length axis (Z by default). |
| error:38 | Invalid gcode ID:38. Tool number greater than max supported value. | The tool number is above Grbl's maximum of 255. |
Reading the error list
- Grbl 1.1 sends the number only (
error:22); Grbl 1.0 and earlier sent a short text message instead, shown in bold in the middle column, so older senders and forum posts quote the text. - An error means Grbl did not run anything on that line. The rest of the program keeps streaming, so most senders stop the job on the first error.
- Errors 23 to 38 were all reported as "Invalid gcode ID:N" in Grbl 1.0.
- Grbl's line buffer is 80 characters (
LINE_BUFFER_SIZEin protocol.h): a longer line gives error:11. Line numbers must be 1 to 9,999,999 (error:27) and tool numbers 0 to 255 (error:38). - Grbl lists the commands it does not support in gcode.c: canned cycles, tool radius compensation, A/B/C axes, expressions, variables, override control, tool changes and switches. Any of them gives error:20. Its supported list is G0–G3, G4, G10 L2/L20, G17–G19, G20/G21, G28/G30 (and .1), G38.2–G38.5, G40, G43.1, G49, G53, G54–G59, G61, G80, G90/G91, G91.1, G92/G92.1, G93/G94, M0, M1 (accepted but ignored), M2, M30, M3–M5, M7 (compile option), M8 and M9.
GRBL alarm codes (ALARM:1 to ALARM:10)
| Code | v1.0 message and meaning | Machine position | What to do |
|---|---|---|---|
| ALARM:1 | Hard limit. Hard limit has been triggered. Machine position is likely lost due to sudden halt. Re-homing is highly recommended. | Likely lost | Find what tripped the switch (and check for electrical noise), reset, then re-home with $H. |
| ALARM:2 | Soft limit. Soft limit alarm. G-code motion target exceeds machine travel. Machine position retained. Alarm may be safely unlocked. | Kept | The program or work offset sends the machine past $130–$132. Fix the program or offset; unlocking with $X is safe. |
| ALARM:3 | Abort during cycle. Reset while in motion. Machine position is likely lost due to sudden halt. Re-homing is highly recommended. | Likely lost | Reset was pressed while moving. Re-home with $H. |
| ALARM:4 | Probe fail. Probe fail. Probe is not in the expected initial state before starting probe cycle when G38.2 and G38.3 is not triggered and G38.4 and G38.5 is triggered. | Not stated | The probe was already triggered (G38.2/G38.3) or not triggered (G38.4/G38.5) at the start. Check probe wiring and $6. |
| ALARM:5 | Probe fail. Probe fail. Probe did not contact the workpiece within the programmed travel for G38.2 and G38.4. | Not stated | The probe did not touch within the programmed travel. Start closer or program a longer probe move. |
| ALARM:6 | Homing fail. Homing fail. The active homing cycle was reset. | Homing not completed | Homing was interrupted by a reset. Run $H again. |
| ALARM:7 | Homing fail. Homing fail. Safety door was opened during homing cycle. | Homing not completed | The safety door opened during homing. Close it and run $H again. |
| ALARM:8 | Homing fail. Homing fail. Pull off travel failed to clear limit switch. Try increasing pull-off setting or check wiring. | Homing not completed | Pull-off did not clear the switch. Increase $27 or check wiring. |
| ALARM:9 | Homing fail. Homing fail. Could not find limit switch within search distances. Try increasing max travel, decreasing pull-off distance, or check wiring. | Homing not completed | No switch was found within the search distance (1.5 × max travel when seeking, 5 × pull-off when locating). Increase $130–$132, decrease $27, or check wiring. |
| ALARM:10 | Homing fail. Homing fail. Second dual axis limit switch failed to trigger within configured search distance after first. Try increasing trigger fail distance or check wiring. | Homing not completed | Dual-axis builds: the second switch did not trigger soon enough after the first. Increase the trigger-fail distance or check wiring. |
Clearing an alarm safely
- $H runs the homing cycle and is the normal way out of an alarm when homing is enabled ($22=1).
- $X kills the alarm lock without homing. Grbl's documentation: use it only in emergencies or to move off a limit switch, make short moves in G91 incremental mode, then home or reset, because "Grbl may not be where you think it is". Startup lines ($N) do not run after $X.
- Ctrl-X (0x18) is a soft reset. Reset while moving raises ALARM:3; reset while stopped keeps the position.
- Hard limits (ALARM:1) and resets in motion (ALARM:3) stop the steppers instantly, so steps are likely lost. A soft limit (ALARM:2) feed-holds first, so Grbl keeps its position.
- ALARM:10 (dual-axis homing) is defined in system.h and in the alarm CSV of Grbl 1.1h; the alarm table in interface.md stops at 9.
Commands you will use while troubleshooting
| Command | What it does |
|---|---|
$ | Prints the help line listing the $ commands. |
$$ | Lists every setting ($0–$132). $x=val changes one, for example $22=1. |
$# | Shows G54–G59 work offsets, G28/G30 positions, G92 offset, tool length offset (TLO) and the last probe (PRB). |
$G | Shows the parser state, for example [GC:G0 G54 G17 G21 G90 G94 M0 M5 M9 T0 S0.0 F500.0]: the active modes plus tool, spindle speed and feed. |
$I | Shows the version and build date (for example 1.1h, 20190830). $I=text stores a machine name of under 80 characters. |
$N | Shows the startup blocks; $N0=line saves one. |
$C | Check mode: parses the program without moving, with the spindle and coolant off. Turning it off does a soft reset. |
$X | Kill alarm lock (see above). |
$H | Run the homing cycle. |
$J=… | Jog, for example $J=G91 G21 X10 F500. Needs axis words and F; only G20/G21, G90/G91 and G53 may be added. |
$RST=$ / $RST=# / $RST=* | Restore settings / clear offsets and G28/G30 positions / restore all Grbl EEPROM data. Grbl resets afterwards. |
$SLP | Sleep: disables spindle, coolant and steppers; only a reset exits, and Grbl wakes in alarm. |
? ~ ! | Real-time: status report, cycle start/resume, feed hold. They need no line ending and act within tens of milliseconds. |
GRBL $ settings with units and defaults
| Setting | Name and what it does | Unit | Default (generic build) |
|---|---|---|---|
| $0 | Step pulse time. Sets time length per step. Minimum 3usec. | µs | 10 |
| $1 | Step idle delay. Sets a short hold delay when stopping to let dynamics settle before disabling steppers. Value 255 keeps motors enabled with no delay. | ms | 25 |
| $2 | Step pulse invert. Inverts the step signal. Set axis bit to invert (00000ZYX). | mask | 0 |
| $3 | Step direction invert. Inverts the direction signal. Set axis bit to invert (00000ZYX). | mask | 0 |
| $4 | Invert step enable pin. Inverts the stepper driver enable pin signal. | boolean | 0 |
| $5 | Invert limit pins. Inverts the all of the limit input pins. | boolean | 0 |
| $6 | Invert probe pin. Inverts the probe input pin signal. | boolean | 0 |
| $10 | Status report options. Alters data included in status reports. | mask | 1 |
| $11 | Junction deviation. Sets how fast Grbl travels through consecutive motions. Lower value slows it down. | mm | 0.010 |
| $12 | Arc tolerance. Sets the G2 and G3 arc tracing accuracy based on radial error. Beware: A very small value may effect performance. | mm | 0.002 |
| $13 | Report in inches. Enables inch units when returning any position and rate value that is not a settings value. | boolean | 0 |
| $20 | Soft limits enable. Enables soft limits checks within machine travel and sets alarm when exceeded. Requires homing. | boolean | 0 |
| $21 | Hard limits enable. Enables hard limits. Immediately halts motion and throws an alarm when switch is triggered. | boolean | 0 |
| $22 | Homing cycle enable. Enables homing cycle. Requires limit switches on all axes. | boolean | 0 |
| $23 | Homing direction invert. Homing searches for a switch in the positive direction. Set axis bit (00000ZYX) to search in negative direction. | mask | 0 |
| $24 | Homing locate feed rate. Feed rate to slowly engage limit switch to determine its location accurately. | mm/min | 25.0 |
| $25 | Homing search seek rate. Seek rate to quickly find the limit switch before the slower locating phase. | mm/min | 500.0 |
| $26 | Homing switch debounce delay. Sets a short delay between phases of homing cycle to let a switch debounce. | ms | 250 |
| $27 | Homing switch pull-off distance. Retract distance after triggering switch to disengage it. Homing will fail if switch isn't cleared. | mm | 1.0 |
| $30 | Maximum spindle speed. Maximum spindle speed. Sets PWM to 100% duty cycle. | rpm | 1000 |
| $31 | Minimum spindle speed. Minimum spindle speed. Sets PWM to 0.4% or lowest duty cycle. | rpm | 0 |
| $32 | Laser-mode enable. Enables laser mode. Consecutive G1/2/3 commands will not halt when spindle speed is changed. | boolean | 0 |
| $100 | X-axis travel resolution. X-axis travel resolution in steps per millimeter. | steps/mm | 250.0 |
| $101 | Y-axis travel resolution. Y-axis travel resolution in steps per millimeter. | steps/mm | 250.0 |
| $102 | Z-axis travel resolution. Z-axis travel resolution in steps per millimeter. | steps/mm | 250.0 |
| $110 | X-axis maximum rate. X-axis maximum rate. Used as G0 rapid rate. | mm/min | 500.0 |
| $111 | Y-axis maximum rate. Y-axis maximum rate. Used as G0 rapid rate. | mm/min | 500.0 |
| $112 | Z-axis maximum rate. Z-axis maximum rate. Used as G0 rapid rate. | mm/min | 500.0 |
| $120 | X-axis acceleration. X-axis acceleration. Used for motion planning to not exceed motor torque and lose steps. | mm/s² | 10.0 |
| $121 | Y-axis acceleration. Y-axis acceleration. Used for motion planning to not exceed motor torque and lose steps. | mm/s² | 10.0 |
| $122 | Z-axis acceleration. Z-axis acceleration. Used for motion planning to not exceed motor torque and lose steps. | mm/s² | 10.0 |
| $130 | X-axis maximum travel. Maximum X-axis travel distance from homing switch. Determines valid machine space for soft-limits and homing search distances. | mm | 200.0 |
| $131 | Y-axis maximum travel. Maximum Y-axis travel distance from homing switch. Determines valid machine space for soft-limits and homing search distances. | mm | 200.0 |
| $132 | Z-axis maximum travel. Maximum Z-axis travel distance from homing switch. Determines valid machine space for soft-limits and homing search distances. | mm | 200.0 |
Setting it up: steps/mm, rates and limits
- Defaults above are
DEFAULTS_GENERICfrom Grbl's defaults.h. A machine maker's firmware usually ships its own defaults, which$RST=$restores, so back up$$before changing anything. - Steps per mm ($100–$102), per Grbl's configuration guide: steps_per_mm = (motor steps per revolution × microsteps) ÷ mm travelled per revolution. A 200-step motor at 16 microsteps on a screw that moves 8 mm per turn gives 200 × 16 ÷ 8 = 400 steps/mm.
- Maximum rate ($110–$112) is also the G0 rapid rate. Grbl's guide: raise it until the motor stalls, then set it 10–20% lower; do the same for acceleration ($120–$122, in mm/s²).
- Settings are always in millimetres, even when $13=1 makes Grbl report positions in inches. Convert with the Unit Converter (25.4 mm per inch).
- Soft limits ($20=1) need homing ($22=1) and correct maximum travel ($130–$132). Homing searches up to 1.5 × max travel, so a too-small $130–$132 also causes ALARM:9.
- Masks such as $2, $3 and $23 are bit flags in the order Z Y X: 1 = X, 2 = Y, 4 = Z, so $3=5 inverts the X and Z directions.
- Grbl talks at 115200 baud (BAUD_RATE in config.h); a sender set to another rate shows garbage or no welcome line (
Grbl 1.1h ['$' for help]). The Baud Rate Calculator works out the bit and byte times.
Sources
- gnea/grbl (Sungeun K. Jeon et al.), doc/csv/error_codes_en_US.csv, alarm_codes_en_US.csv, setting_codes_en_US.csv, 2019 (github.com/gnea/grbl/tree/master/doc/csv). Used for: every error and alarm number, the v1.0 message and the description; setting names and units.
- gnea/grbl, Grbl Interface Basics (doc/markdown/interface.md), 2019 (github.com/gnea/grbl/blob/master/doc/markdown/interface.md). Used for: ok / error:N / ALARM:N messages, longer error explanations, homing search distances.
- gnea/grbl, Grbl v1.1 Commands (doc/markdown/commands.md), 2019 (github.com/gnea/grbl/blob/master/doc/markdown/commands.md). Used for: $ commands, $X / $H, jogging rules, real-time commands, $RST.
- gnea/grbl, Grbl v1.1 Configuration (doc/markdown/settings.md), 2019 (github.com/gnea/grbl/blob/master/doc/markdown/settings.md). Used for: what each $ setting does; the steps/mm formula.
- gnea/grbl, firmware source: grbl/defaults.h, config.h, protocol.h, gcode.c, system.h, report.h, 2019 (github.com/gnea/grbl/tree/master/grbl). Used for: default values, 115200 baud, 80-character line buffer, line number and tool number limits, alarm 10, unsupported-command list.
- All files were downloaded from the gnea/grbl master branch on 6 October 2026. The tables are generated from
assets/data/grbl-codes.json, so the page and any tool that reads that file show the same values. - This page covers gnea/grbl 1.1 only. Forks of Grbl are separate firmware; check their own documentation before applying these numbers to them.
Frequently asked questions
What does GRBL error:20 mean?
error:20 is "Unsupported or invalid g-code command found in block". Grbl 1.1 has no canned cycles (G81–G89), no cutter compensation (G41/G42), no G43 (only G43.1), no M6 tool change and no A/B/C axes, so a CAM post written for an industrial control often triggers it. Use a Grbl post-processor.
What does GRBL error:22 mean?
error:22 is "Undefined feed rate": a G1, G2 or G3 arrived before any F word was set. Add an F value (in mm/min or in/min) on or before the first cutting move.
How do I clear a GRBL alarm?
Send $H to run the homing cycle, which clears the alarm and re-establishes machine position, or $X to unlock without homing. Grbl's documentation says to use $X only to move off a switch or in an emergency, with short G91 moves, and then home or reset, because the position may be lost.
What is GRBL ALARM:1?
ALARM:1 is a hard limit: a limit switch tripped and Grbl stopped instantly. Machine position is likely lost, so Grbl recommends re-homing ($H) after you find what tripped the switch. ALARM:2 (soft limit) is different: the target was beyond $130–$132, position is kept and $X is safe.
Why does GRBL start in alarm and say error:9?
With homing enabled ($22=1), Grbl powers up in alarm because it does not know where the machine is, and it locks out G-code (error:9) until you home with $H or unlock with $X.
Was this article helpful?