LaserParams

GRBL Error Codes: Complete Troubleshooting Guide

GRBL error codes are command-level rejections—the controller reads a G-code line, finds a problem, and refuses to execute it. Unlike alarm codes (which are hardware-level events during motion), errors mean the machine never moved. This guide covers every error code from error:1 through error:38 with plain-English explanations, exact console commands, and step-by-step fixes that work with LightBurn, xTool, OMTech, Sculpfun, Atomstack, and any GRBL-based controller.

Quick Reference Table

CodeDescription
1G-code word expected
2Numeric value format error
3Invalid $ statement
4Negative value for positive-only setting
5Homing not enabled (setting)
6Min step pulse time exceeded
7EEPROM read fail
8$ command requires idle state
9Locked out during alarm
10Soft limits require homing enabled
11Max characters per line exceeded
12$ setting exceeds step rate max
13Safety door detected
14Build info line length exceeded
15Homing not enabled
16No homing cycle configured
17Homing switch not found
20Unsupported G-code command
21Duplicate G-code word in block
22Feed rate not set
23Integer value required
24Negative value invalid
25Homing not configured for axis
26Decimal without value
27Missing axis word in command
28No axis word in command block
29Invalid line number
30Missing value word
31G59.x WCS not supported
32G53 invalid with motion mode
33Axis word without motion command
34No axis word with G2/G3
35Motion command invalid target
36Arc radius error
37No axis words found
38Spindle not turned on

Codes 18-19 are not defined in the standard GRBL specification. Click a code number to jump to the detailed troubleshooting section.

error:1—G-code Word Expected

What it means

GRBL expected a valid G-code word (like G0, G1, M3, etc.) but received a line that was either empty or contained only whitespace and comments. The controller cannot execute a line that has no instruction.

Common causes

  1. 1.The G-code file contains blank lines or lines with only comments.
  2. 2.A post-processor or text editor introduced empty lines during editing.
  3. 3.A macro or custom G-code header has an incomplete command.
  4. 4.The file was corrupted during transfer or saving.

How to fix it

  1. 1Open your G-code file in a text editor and search for blank lines.
  2. 2Remove any lines that contain only whitespace or are completely empty.
  3. 3Check the first and last few lines of the file for incomplete commands.
  4. 4Re-export the file from LightBurn if the issue persists.
  5. 5Send the file again and confirm the error is resolved.

LightBurn tip

LightBurn generates clean G-code by default. If you see error:1, it usually means a custom Start G-code or End G-code block in Edit > Device Settings has a blank line. Check those fields first.

error:2—Numeric Value Format Error

What it means

GRBL found a G-code letter (like X, Y, F, S) but the number following it was missing, contained invalid characters, or was in an unrecognizable format. Every G-code word must have a properly formatted numeric value after the letter.

Common causes

  1. 1.A G-code word is missing its numeric value (e.g., G1 X Y10 instead of G1 X5 Y10).
  2. 2.The number contains invalid characters such as extra decimal points or letters.
  3. 3.A locale issue caused commas to replace decimal points (e.g., X10,5 instead of X10.5).
  4. 4.Copy-pasting G-code introduced hidden Unicode characters.

How to fix it

  1. 1Check the console output in LightBurn to identify which line triggered the error.
  2. 2Open the G-code file and find the offending line. Look for missing numbers after command letters.
  3. 3Ensure all decimal values use periods, not commas (X10.5, not X10,5).
  4. 4If the file was manually edited, re-export from LightBurn to get clean G-code.
  5. 5Test by sending a simple command like G0 X10 Y10 to verify the controller accepts properly formatted code.

LightBurn tip

If you are using a computer with a non-English locale (e.g., German or French), check that LightBurn is outputting periods for decimals. Go to Edit > Device Settings and verify the number format.

error:3—Invalid $ Statement

What it means

GRBL received a line starting with $ but could not recognize it as a valid system command. GRBL has a fixed set of $ commands, and anything outside that set is rejected.

Common causes

  1. 1.A typo in the system command (e.g., $home instead of $H).
  2. 2.Using a command from a different GRBL version or fork that your controller does not support.
  3. 3.Extra characters after a valid command (e.g., $H1 instead of $H).
  4. 4.A G-code file accidentally contains $ commands meant for the console.

How to fix it

  1. 1Review the command you typed and compare it against the valid GRBL $ commands.
  2. 2Valid settings commands are $0 through $132 followed by = and a value (e.g., $110=1000).
  3. 3Valid system commands are: $$, $#, $G, $I, $N, $H, $X, $C, $RST=$, $RST=#, $RST=*.
  4. 4If the command came from a G-code file, remove it and re-send.
  5. 5Type $$ to list all current settings and verify your controller firmware version.

LightBurn tip

LightBurn never sends $ commands during normal job execution. If you see error:3, it is likely from something you typed in the Console tab or from a custom macro. Double-check your macros in the Console panel.

error:8—Dollar Setting Disabled While Idle

What it means

GRBL only allows you to modify $ settings when the machine is in an idle state (not running, not in alarm, not in a homing cycle). This prevents settings changes during critical operations.

Common causes

  1. 1.The machine is in an alarm state and needs to be unlocked with $X first.
  2. 2.A job is currently running and you attempted to change settings mid-job.
  3. 3.The machine is in a check mode ($C) and settings changes are blocked.
  4. 4.A homing cycle is in progress.

How to fix it

  1. 1Check the machine state by typing ?in the console. Look for the state indicator (Idle, Alarm, Run, etc.).
  2. 2If the state is Alarm, type $X to unlock the machine.
  3. 3If the state is Run, wait for the current job to finish or press the Stop button.
  4. 4Once the state shows Idle, retry your $ setting command.
  5. 5Verify the change took effect by typing $$ and checking the value.

LightBurn tip

In LightBurn, the status bar at the bottom shows the current machine state. Wait until it says "Ready" or "Idle" before changing GRBL settings through the console.

error:9—Locked Out During Alarm

What it means

GRBL entered an alarm state (from a limit switch trigger, failed homing, or power-on without homing) and is now locked. In alarm lockout, GRBL rejects all G-code motion commands until you explicitly unlock or home the machine.

Common causes

  1. 1.The machine was just powered on and requires homing before accepting commands.
  2. 2.A previous alarm (limit switch, homing failure) was not cleared.
  3. 3.You tried to start a job without first unlocking or homing the machine.
  4. 4.The machine lost its position due to a reset and needs to re-establish home.

How to fix it

  1. 1Type $X in the console to unlock GRBL. This clears the alarm state.
  2. 2If your machine has homing switches, type $H to run a full homing cycle instead.
  3. 3After unlocking or homing, verify the state by typing ?and confirming it shows Idle.
  4. 4Resend your G-code command or restart the job.
  5. 5If the alarm immediately returns, there is an underlying hardware issue. Check the alarm code that originally triggered the lockout.

LightBurn tip

This is the most common error when first connecting to a GRBL laser in LightBurn. If your machine shows error:9 on every startup, go to Edit > Device Settings and enable "Auto-home on connect" or manually click the Home button before starting a job.

error:15—Homing Not Enabled

What it means

GRBL received the $H homing command, but the homing cycle is disabled in the configuration (setting $22 is set to 0). The controller will not attempt to seek limit switches until homing is explicitly enabled.

Common causes

  1. 1.The GRBL setting $22 is set to 0 (homing disabled).
  2. 2.The controller was reset to factory defaults which may have homing off by default.
  3. 3.A firmware update cleared the EEPROM settings.
  4. 4.The machine was configured without limit switches and homing was intentionally disabled.

How to fix it

  1. 1Type $22 in the console to check the current homing setting.
  2. 2If it returns $22=0, enable homing by typing $22=1.
  3. 3Verify your machine physically has limit switches installed before enabling homing.
  4. 4After enabling, type $H to test the homing cycle.
  5. 5If homing fails after enabling, check your limit switch wiring and the $23 homing direction mask.

LightBurn tip

When setting up a new machine in LightBurn, the Device Setup wizard asks about homing. If you selected "no homing" but your machine has switches, you can change it later in Edit > Device Settings or simply type $22=1 in the Console.

error:17—Homing Cycle Failed

What it means

GRBL initiated a homing cycle but one or more axes traveled the full search distance ($25) without detecting a limit switch trigger. The controller aborted the cycle because it could not establish a known position.

Common causes

  1. 1.A limit switch is disconnected or has a broken wire.
  2. 2.The limit switch is faulty and does not trigger when pressed.
  3. 3.The switch is wired to the wrong pin on the controller board.
  4. 4.The homing search distance ($25) is shorter than the physical axis travel.
  5. 5.The homing direction ($23 mask) is sending the axis away from the switch.

How to fix it

  1. 1Manually press each limit switch by hand while typing ?in the console to verify GRBL detects the pin change.
  2. 2Inspect the wiring for the axis that failed. Look for loose connectors or cut wires.
  3. 3Check the homing search distance: type $25 to see the current value. It should exceed your longest axis length.
  4. 4Verify the homing direction mask: type $23. If axes home the wrong way, adjust the bitmask.
  5. 5If switches are optical (no-contact type), ensure they are powered and the LED indicator activates.
  6. 6Replace any suspect switch with a known-working one to isolate the fault.

LightBurn tip

In LightBurn, you can test limit switches by going to the Move window and watching the status indicators while manually pressing each switch. This helps identify which switch is not being detected.

error:20—Unsupported G-code Command

What it means

The G-code line contains a command that is not part of the GRBL supported command set. GRBL implements a subset of the full G-code standard, and commands from CNC machining centers or other firmware may not be recognized.

Common causes

  1. 1.The G-code was generated by a post-processor for a different controller (Marlin, Mach3, LinuxCNC).
  2. 2.A tool change command (M6) or tool length offset (G43) is present, which GRBL does not support.
  3. 3.A canned drilling cycle (G81-G89) was included.
  4. 4.Custom M-codes from a different firmware are in the file.

How to fix it

  1. 1Check the LightBurn console to see which specific line triggered the error.
  2. 2Open the G-code file and locate the unsupported command.
  3. 3Remove or comment out the unsupported command (prefix the line with a semicolon).
  4. 4If the file was not generated by LightBurn, re-export it using a GRBL-compatible post-processor.
  5. 5Refer to the GRBL supported G-code list: G0, G1, G2, G3, G38.x, G10, G17-G19, G20-G21, G28, G30, G43.1, G49, G53-G59, G80, G90-G91, G92, G93-G94.

LightBurn tip

LightBurn automatically generates GRBL-compatible G-code when your device is set to GRBL. If you see error:20, check if you accidentally set the device profile to a different controller type in Edit > Device Settings.

error:22—Feed Rate Not Set

What it means

GRBL requires a feed rate (F value) for any controlled motion command (G1, G2, G3). If no F value has been set in the current session and the motion command does not include one, GRBL rejects the line.

Common causes

  1. 1.A G1, G2, or G3 command was sent without an F parameter and no previous F value was set.
  2. 2.The G-code file is missing the initial feed rate declaration at the top.
  3. 3.A custom Start G-code block in LightBurn does not include a default feed rate.
  4. 4.The controller was reset mid-job, clearing the previously set feed rate from memory.

How to fix it

  1. 1Add an F parameter to the motion command. For example: G1 X10 Y10 F1000 (1000 mm/min).
  2. 2Check the beginning of your G-code file for an F value in the first few motion commands.
  3. 3If testing manually in the console, always include F with your first G1 command after connecting.
  4. 4After a reset or reconnect, resend the feed rate before starting motion commands.

LightBurn tip

LightBurn always includes feed rates in generated G-code. If you see error:22, it is almost certainly from a command you typed manually in the Console without an F value. Try G1 X10 F500 to set the rate.

error:23—Integer Value Required

What it means

Certain GRBL settings and G-code parameters only accept integer (whole number) values. Sending a decimal value for these parameters triggers this error.

Common causes

  1. 1.A $ setting was given a decimal value when it requires an integer (e.g., $0=10.5 instead of $0=10).
  2. 2.A G-code line number (N) was given a decimal.
  3. 3.A tool number or other integer-only parameter has a fractional value.

How to fix it

  1. 1Identify which setting or parameter triggered the error from the console output.
  2. 2Round the value to the nearest whole number.
  3. 3Resend the command with the corrected integer value.
  4. 4For GRBL settings, type $$ to see the current values and their expected formats.

LightBurn tip

This error typically occurs when manually adjusting GRBL settings via the Console. LightBurn-generated G-code handles number formatting correctly, so this is rarely seen during normal operation.

error:24—Negative Value Invalid

What it means

Many GRBL settings (like step counts, speeds, and distances) must be positive numbers. Sending a negative value for these parameters is not allowed.

Common causes

  1. 1.A negative value was entered for a $ setting like acceleration or max rate (e.g., $120=-500).
  2. 2.A typo introduced a minus sign before the value.
  3. 3.A script or macro generated a negative parameter value.

How to fix it

  1. 1Check the console to identify which parameter received the negative value.
  2. 2Remove the negative sign and resend with a positive value.
  3. 3Type $$ to review all settings and confirm they are positive where required.
  4. 4If a macro generated the value, fix the macro logic to prevent negative outputs.

LightBurn tip

This error is rare during normal LightBurn use. If you encounter it, check any custom Start G-code or macros in Edit > Device Settings for accidentally negative parameters.

error:33—Motion Command Target Invalid

What it means

GRBL evaluated a motion command and determined the target position is invalid. This can happen when the move exceeds the configured machine boundaries, when axis words are present without a corresponding motion mode, or when the target results in an impossible move.

Common causes

  1. 1.The target position exceeds the machine travel limits set in $130/$131/$132.
  2. 2.The job origin combined with the design dimensions extends past the work area boundary.
  3. 3.An axis word was included on a line without an active motion mode (G0, G1, G2, G3).
  4. 4.Coordinate values are unreasonably large due to a unit mismatch (inches vs. millimeters).

How to fix it

  1. 1Check your max travel settings by typing $130, $131, and $132 in the console.
  2. 2Verify the machine is set to the correct unit mode: G20 for inches, G21 for millimeters.
  3. 3In LightBurn, use the Frame button to preview the job boundary before running.
  4. 4Reposition the job origin toward the center of the bed to ensure the full design fits.
  5. 5If the coordinates seem much too large, check that LightBurn and GRBL are both set to the same unit (usually millimeters).

LightBurn tip

Go to Edit > Device Settings and verify the workspace size matches your machine. LightBurn will show a red boundary warning if the design exceeds the configured area. Also check that the "Start From" setting is appropriate for your workflow.

error:38—Spindle Not Turned On

What it means

GRBL requires the spindle (which controls the laser in laser mode) to be active with a defined power level before certain operations. If no M3/M4 command with an S value was issued, the controller rejects the motion.

Common causes

  1. 1.No M3 or M4 spindle command was sent before the motion commands.
  2. 2.The S (spindle speed/laser power) value was not included with the M3/M4 command.
  3. 3.A custom G-code file is missing the spindle initialization at the start.
  4. 4.The controller was reset mid-job, clearing the spindle state.

How to fix it

  1. 1Send M3 S1000 (or your desired power level) in the console before running motion commands.
  2. 2Check the beginning of your G-code file for an M3 or M4 command with an S value.
  3. 3If testing manually, always initialize the spindle before sending G1 moves: M3 S500 then G1 X10 F1000.
  4. 4After a reset or reconnect, resend the spindle command before resuming work.

LightBurn tip

LightBurn always includes proper M3/M4 and S commands in generated G-code. If you see error:38, check your custom Start G-code block in Edit > Device Settings. Also verify that $30 (max spindle speed) and $31 (min spindle speed) are set correctly for your laser.

GRBL Errors vs. Alarms: Key Differences

Understanding whether you are dealing with an error or an alarm determines your troubleshooting approach.

Errors (error:1–error:38)

Errors are command-level rejections. They fire when GRBL receives a G-code line it cannot parse or execute—like an unsupported command, a missing feed rate, or an invalid number. The machine does not move. Fix the G-code and resend.

Alarms (ALARM:1–ALARM:9)

Alarms are hardware-level events that occurred during motion. Something physically happened—a switch triggered, a homing sequence failed, a probe lost contact. The machine locks out until you type $X to unlock and resolve the issue. See our GRBL alarm codes guide for details.

Frequently Asked Questions

What is the difference between GRBL errors and alarms?
GRBL errors (error:1, error:2, etc.) are command-level rejections. They happen when GRBL receives a G-code line it cannot parse or execute, such as an unsupported command or a missing feed rate. The machine does not move. GRBL alarms (ALARM:1 through ALARM:9) are hardware-level events that occur during motion, like hitting a limit switch or failing a homing cycle. Errors are fixed by correcting the G-code; alarms require resolving the physical issue and unlocking with $X.
How do I see error codes in LightBurn?
Open the Console panel in LightBurn (Window > Console if it is not visible). Every command sent to the controller and every response is logged here. When GRBL rejects a command, you will see "error:XX" in red text along with the G-code line that caused it. You can scroll through the console history to find the exact line and error code.
Why do I get Error 9 after powering on?
Error 9 means the machine is in alarm lockout and rejecting G-code commands. This happens because most GRBL controllers enter an alarm state on power-up when homing is enabled ($22=1), requiring you to home the machine before it accepts commands. Type $H to run the homing cycle, or $X to unlock without homing. In LightBurn, you can enable auto-homing on connect in Edit > Device Settings.
How do I enable homing on my GRBL machine?
Type $22=1 in the console to enable homing. Make sure your machine has limit switches physically installed and wired to the controller before enabling this. After enabling, set the homing direction with $23 (bitmask for which axes home in the positive direction), the search speed with $24, the locate speed with $25, and the pull-off distance with $27. Then test with $H.
What does "feed rate not set" mean?
Error 22 means you sent a controlled motion command (G1, G2, or G3) without ever setting a feed rate (F value) in the current session. GRBL needs to know how fast to move. Add an F parameter to your command, for example: G1 X10 Y10 F1000 sets the feed rate to 1000 mm/min. Once set, the F value persists for subsequent commands until changed or the controller is reset.
Why does my laser say "unsupported G-code command"?
Error 20 means GRBL received a G-code command it does not support. GRBL only implements a subset of the full G-code standard. Commands like M6 (tool change), G43 (tool length offset), or canned cycles (G81-G89) are not available. This usually happens when G-code was generated by a post-processor for a different controller. In LightBurn, make sure your device profile is set to GRBL in Edit > Device Settings, and re-export the file.

Still stuck on a GRBL error?

Paste your error code and the G-code line that caused it. Our AI assistant will diagnose the problem and walk you through the fix.

Ask the AI Assistant

More Laser Guides

GRBL Alarm CodesTroubleshoot ALARM 1–9Wood SettingsCut & engrave parametersAcrylic SettingsCO2 & diode guideLeather SettingsVeg-tanned engravingTroubleshootingFix common problems